Merge pull request #2334 from ethereum/whatsupdocs

update to docs - run.md, udapp.md, contract_metadata.md, & FAQ

FAQ.md

@@ -1,7 +0,0 @@
-**Q: compiler might be in a non-sane state**
-``error: "Uncaught JavaScript exception: RangeError: Maximum call stack size exceeded.
-The compiler might be in a non-sane state, please be careful and do not use further compilation data to deploy to mainnet.
-It is heavily recommended to use another browser not affected by this issue (Firefox is known to not be affected)."``
-
-**A: Old versions of solidity compiler had this problem with chrome.**
-Please change the compiler version in Solidity Plugin to the newer one or use another browser.

docs/FAQ.md

@@ -0,0 +1,80 @@
+FAQ
+===
+
+### Solidity compiler
+
+**Q: Error: compiler might be in a non-sane state**
+```
+error: "Uncaught JavaScript exception: RangeError: Maximum call stack size exceeded.
+The compiler might be in a non-sane state, please be careful and do not use further compilation data to deploy to mainnet.
+It is heavily recommended to use another browser not affected by this issue (Firefox is known to not be affected)."
+```
+
+**A:** Old versions of solidity compiler had this problem with chrome.
+Please change the compiler version in Solidity Plugin to the newer one or use another browser.
+
+**Q:** I’m getting an issue with Maximum call stack exceed and various other errors, can't compile.
+
+**A:**  Try a different browser or a newer solidity compiler version.
+
+### Deploy & Run
+
+**Q:** I am using an Infura endpoint in my app, but when I try to deploy against that endpoint in remix IDE selecting "web3 provider" and putting my endpoint in, it's telling me that it can't connect
+
+**A:** If the endpoint you are using is http, it won't work.
+
+**Q:** Where is deploy button?
+
+**A:** Its in the Deploy & Run module. If you haven't activated that module, you should do that by clicking Deploy & Run module in the Plugin Manager.
+You could also activate everything you need to work with solidity on the landing page ( click the remix logo at the top left for the screen) and click the "Solidity" button in the environment section.
+
+**Q:** How to pass a tuple to a public function in Remix?
+
+**A:** Pass it as an array [].
+
+**Q:** How to input a struct as input to a parameter of a function in the Deploy & Run module?
+
+**A:** For inputting a struct, just like a tuple, pass it in as an array [].  Also you need to put in the line:
+
+`pragma experimental ABIEncoderV2;` at the top of the solidity file.
+
+For example, here's a solidity file with a struct is an input parameter.
+
+```
+pragma solidity >=0.4.22 <0.6.0;
+pragma experimental ABIEncoderV2;
+
+contract daPeeps {
+    struct Peep {uint a; uint b;} // declaration of Peep type
+    Peep peep; //declaration of an object of Peep type
+
+    constructor () public
+    {
+        peep.a = 0; // definition/initialisation of object
+        peep.b = 0; //
+    }
+
+    function initPeepToPeep(Peep memory i) public payable {
+        peep.a = i.a;
+        peep.b = i.b;
+    }
+    function setPeep(uint a, uint b) public payable {
+        peep.a = a;
+        peep.b = b;
+    }
+
+    function getPeep() public view returns(Peep memory)
+    {
+        return peep;
+    }
+}
+```
+
+The input of initPeepToPeeps takes a struct.  If you input
+`[1,2]` the transaction will go through.
+
+
+
+
+
+

docs/index.rst

@@ -60,6 +60,7 @@ Useful links:
    contract_metadata
    create_deploy
    tutorial_debug
+   FAQ
    import
    remix_commands
    remixd
@@ -79,7 +80,7 @@ Useful links:
 
 .. toctree::
    :maxdepth: 2
-   :caption: Tutorials and workshops slides
+   :caption: Tutorials and workshops
 
    remix_tutorials_github
 

docs/run.md

@@ -1,11 +1,11 @@
-Run & Deploy
+Deploy & Run
 ============
 
-The Run tab allows you to send transactions to the current environment.
+The Deploy & Run module allows you to send transactions to the current environment.
 
 To get to the Run & Deploy module - click the run icon in the icon panel.
 
-In order to use this module you need to have a contract compiled.  So if there is file name in the contract pulldown menu ( in the image below it's the pulldown that says **Ballot**), then you can interact with this contract.  If nothing is there - then you need to select a contract - make it the active contract in the main panel, ( in the image below - on the right side of the page - in the main panel - you see the ballot.sol so it is the active contract) then go to the compiler module and compile it.
+In order to use this module you need to have a contract compiled.  So, if there is a contract name in the contract select box (in the image below it's the pulldown that says **Ballot**), then you can interact with this contract.  If nothing is there - then you need to select a contract. And you do that by clicking the file in the editor panel to make it the active tab ( in the image below - on the right side of the page - in the main panel - you see the ballot.sol so it is the active contract).  Once its active, then go to the compiler module and compile it. Then come back to Deploy & Run.
 
 ![](images/a-runtab1.png)
 
@@ -15,49 +15,44 @@ Run Setup
 The following settings allow you to directly influence the transaction
 execution:
 
-Environment:
+**Environment:**
 
 -   `JavaScript VM`: All the transactions will be executed in
     a sandbox blockchain in the browser. This means nothing
-    will be persisted and a page reload will restart a new
-    blockchain from scratch, the old one will not be saved.
+    will be persisted when you reload the page. The JsVM is its own blockchain and on each reload it will start a new blockchain, the old one will not be saved.
 
 -   `Injected Provider`: Remix will connect to an injected
-    web3 provider. `Metamask` is an example of
-    providers that inject web3, thus can be used with this
-    option.
+    web3 provider. `Metamask` is an example of a 
+    provider that inject web3.
 
--   `Web3 Provider`: Remix will connect to a remote node. You
-    will need to provide the URL address to the selected
-    provider: geth, parity or any Ethereum client.
+-   `Web3 Provider`: Remix will connect to a remote node. You will need to provide the URL to the selected provider: geth, parity or any Ethereum client.
 
+**Account:**
 -   Account: the list of accounts associated with the current
-     environment (and their associated balances).
+     environment (and their associated balances).  On the JsVM, you have a choice of 5 accounts.  If using Injected Web3 with MetaMask, you need to change the account in MetaMask.
 
--   Gas Limit: the maximum amount of gas that can be set for all the
+**Gas Limit:**
+-   This sets the maximum amount of gas that will be allowed for all the
      transactions created in Remix.
 
--   Value: the amount of value for the next created transaction (this
-     value is always reset to 0 after each transaction execution).
+**Value:**
+-   This sets the amount of ETH, WEI, GWEI etc that is sent to a contract or a payable function.  ( Note: payable functions have a red button). The value is always reset to 0 after each transaction execution).
 
  ![](images/a-Runtab-deploy-atAddress.png)
 
 Initiate Instance
 -----------------
 
-This section contains the list of compiled contracts and 2 actions:
-
--   `At Address` assumes the given address is an instance of the
-    selected contract. It is then possible to interact with an already
-    deployed contract. There's no check at this point, so be careful
-    when using this feature, and be sure you trust the contract at that
-    address.
+-   In the image above the select box is set to Ballot.  This select box will contain the list of compiled contracts.
 
 -   `Deploy` send a transaction that deploys the selected contract. When
     the transaction is mined, the newly created instance will be added
     (this might take several seconds). Note that if the `constructor`
     has parameters, you need to specify them.
 
+-   `At Address` this is used at access a contract that has already been deployed. It assumes that the given address is an instance of the selected contract.  **Note:** There's no check at this point, so be careful when using this feature, and be sure you trust the contract at that address.
+
+
 Pending Instances
 -----------------
 
@@ -69,12 +64,12 @@ pending transactions is updated and the transaction is added to the log
 Using the ABI
 ------------
 
-Using `Deploy` or `At Address` is a classic use case of Remix. It is
-possible though to interact with a contract by using its ABI. The ABI is
+Using `Deploy` or `At Address` is a classic use case of Remix. However, it is
+possible to interact with a contract by using its ABI. The ABI is
 a JSON array which describe its interface.
 
 To interact with a contract using the ABI, create a new file in Remix
-with extension `*.abi` and copy the ABI content to it. Then in the input
+with extension `*.abi` and copy the ABI content to it. Then, in the input
 next to `At Address`, put the Address of the contract you want to
 interact with. Click on `At Address`, a new "connection" with the
 contract will popup below.
@@ -82,29 +77,34 @@ contract will popup below.
 Using the Recorder
 ------------------
 
-The Recorder allows to save a bunch of transactions in a JSON file and
+The Recorder is a tool used to save a bunch of transactions in a JSON file and
 rerun them later either in the same environment or in another.
 
-Saving to JSON allows to easily check the transaction list, tweak input
-parameters, change linked library, etc...
+Saving to the JSON file ( by default its called senario.json) allows one to easily check the transaction list, tweak input parameters, change linked library, etc...
+
+There are many use cases for the recorder.  
+
+For instance:
 
-We can find many use cases for the recorder, for instance:
 -   After having coded and tested contracts in a constrained
-    environment (like the JavaScript VM), it could be interesting to
-    redeploy them easily in a more persisted environment (like a
-    Geth node) in order to check whether everything behaves normally
-    in a classic environment.
+    environment (like the JavaScript VM), you could then change the environment and redeploy it to a more realistic environment like a test net with an **injected web3** or to a Geth node. By using the generated **senario.json** file, you will be using all the same settings that you used in the Javascript VM.  And this mean that you won't need to click the interface 100 times or whatever to get the state that you achieved originally.  So the recorder could be a tool to protect your sanity.
+    
+    You can also change the settings in the senario.json file to customize the playback.
+
 -   Deploying contract does often require more than creating one
-    transaction.
--   Working in a dev environment does often require to setup the
-    state in a first place.
+    transaction and so the recorder will automate this deployment.
+
+-   Working in a dev environment often requires to setup the
+    state in a first place.  
 
 ![](images/a-runtab-recorder.png)
 
-Saving a record ends up with the creation of this type of content (see
-below):
+### senario.json
+To create this file in the recorder, you first of course need to have run some transactions.  In the image above - it has a `0` next to **Transactions Recorded**.  So this isn't the right moment to save transactions because - well because there aren't any.  Each time you make a transaction, that number will increment.  Then when you are ready, click the floppy disk icon and the senario.json file will be created.
+
+The JSON file below is an example of the senario.json file.
 
-In that specific record, 3 transactions are executed:
+In it, 3 transactions are executed:
 
 The first corresponds to the deployment of the lib `testLib`.
 
@@ -124,7 +124,6 @@ All these transactions are created using the value of the accounts
 `account{0}`.
 
 ``` 
-{.sourceCode .none}
 {
 "accounts": {
     "account{0}": "0xca35b7d915458ef540ade6068dfe2f44e8fa733c"

docs/udapp.md

@@ -54,3 +54,11 @@ In the expanded view, strings do not need to be wrapped.
 Clicking the clipboard icon will encode the inputs and will copy them.  Only a valid set of inputs can be encoded.  
 
 So if you made a mistake and put a uint8 where an address should have been, clicking the clipboard here will give you an error.
+
+### Passing in a tuple or a struct to a function
+To pass a tuple in, you need to put in an an array [].
+
+Similarly, to pass in a struct as a parameter of a function, it needs to be put in as an array [].  Also note that the line
+`pragma experimental ABIEncoderV2;`
+needs to put in at the top of the solidity file.
+