contract-artifacts: add devdoc to ERC20Token.json

Artifact changes crafted manually: re-generated artifacts from within
@0x/contracts-erc20, and then copied them into @0x/contract-artifacts,
but only committed the changes that added devdoc.

Modified @0x/contracts-erc20/compiler.json to include devdoc in the
hopes that next time contract-artifacts are re-generated en masse, the
devdoc output will just come along for the ride.

Compiling ERC20 TypeScript wrappers after adding devdoc to the artifacts
revealed some inconsistencies in the types.  ethereum-types'
DevdocOutput REQUIRED many fields which are not always present,
depending the devdoc contents itself.  Relaxing the requirement had some
ramifications.

contracts/erc20/compiler.json

@@ -17,7 +17,8 @@
                     "evm.bytecode.object",
                     "evm.bytecode.sourceMap",
                     "evm.deployedBytecode.object",
-                    "evm.deployedBytecode.sourceMap"
+                    "evm.deployedBytecode.sourceMap",
+                    "devdoc"
                 ]
             }
         }

packages/contract-artifacts/artifacts/ERC20Token.json

@@ -82,6 +82,53 @@
                 "type": "event"
             }
         ],
+        "devdoc": {
+            "methods": {
+                "allowance(address,address)": {
+                    "params": {
+                        "_owner": "The address of the account owning tokens",
+                        "_spender": "The address of the account able to transfer the tokens"
+                    },
+                    "return": "Amount of remaining tokens allowed to spent"
+                },
+                "approve(address,uint256)": {
+                    "details": "`msg.sender` approves `_spender` to spend `_value` tokens",
+                    "params": {
+                        "_spender": "The address of the account able to transfer the tokens",
+                        "_value": "The amount of wei to be approved for transfer"
+                    },
+                    "return": "Always true if the call has enough gas to complete execution"
+                },
+                "balanceOf(address)": {
+                    "details": "Query the balance of owner",
+                    "params": {
+                        "_owner": "The address from which the balance will be retrieved"
+                    },
+                    "return": "Balance of owner"
+                },
+                "totalSupply()": {
+                    "details": "Query total supply of token",
+                    "return": "Total supply of token"
+                },
+                "transfer(address,uint256)": {
+                    "details": "send `value` token to `to` from `msg.sender`",
+                    "params": {
+                        "_to": "The address of the recipient",
+                        "_value": "The amount of token to be transferred"
+                    },
+                    "return": "True if transfer was successful"
+                },
+                "transferFrom(address,address,uint256)": {
+                    "details": "send `value` token to `to` from `from` on the condition it is approved by `from`",
+                    "params": {
+                        "_from": "The address of the sender",
+                        "_to": "The address of the recipient",
+                        "_value": "The amount of token to be transferred"
+                    },
+                    "return": "True if transfer was successful"
+                }
+            }
+        },
         "evm": {
             "bytecode": {
                 "object": "0x608060405234801561001057600080fd5b506106a0806100206000396000f3006080604052600436106100775763ffffffff7c0100000000000000000000000000000000000000000000000000000000600035041663095ea7b3811461007c57806318160ddd146100c157806323b872dd146100e857806370a082311461011f578063a9059cbb1461014d578063dd62ed3e1461017e575b600080fd5b34801561008857600080fd5b506100ad73ffffffffffffffffffffffffffffffffffffffff600435166024356101b2565b604080519115158252519081900360200190f35b3480156100cd57600080fd5b506100d6610225565b60408051918252519081900360200190f35b3480156100f457600080fd5b506100ad73ffffffffffffffffffffffffffffffffffffffff6004358116906024351660443561022b565b34801561012b57600080fd5b506100d673ffffffffffffffffffffffffffffffffffffffff60043516610487565b34801561015957600080fd5b506100ad73ffffffffffffffffffffffffffffffffffffffff600435166024356104af565b34801561018a57600080fd5b506100d673ffffffffffffffffffffffffffffffffffffffff6004358116906024351661063c565b33600081815260016020908152604080832073ffffffffffffffffffffffffffffffffffffffff8716808552908352818420869055815186815291519394909390927f8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925928290030190a350600192915050565b60025490565b73ffffffffffffffffffffffffffffffffffffffff83166000908152602081905260408120548211156102bf57604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601a60248201527f45524332305f494e53554646494349454e545f42414c414e4345000000000000604482015290519081900360640190fd5b73ffffffffffffffffffffffffffffffffffffffff8416600090815260016020908152604080832033845290915290205482111561035e57604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601c60248201527f45524332305f494e53554646494349454e545f414c4c4f57414e434500000000604482015290519081900360640190fd5b73ffffffffffffffffffffffffffffffffffffffff831660009081526020819052604090205482810110156103f457604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601060248201527f55494e543235365f4f564552464c4f5700000000000000000000000000000000604482015290519081900360640190fd5b73ffffffffffffffffffffffffffffffffffffffff80841660008181526020818152604080832080548801905593881680835284832080548890039055600182528483203384528252918490208054879003905583518681529351929391927fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef9281900390910190a35060019392505050565b73ffffffffffffffffffffffffffffffffffffffff1660009081526020819052604090205490565b3360009081526020819052604081205482111561052d57604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601a60248201527f45524332305f494e53554646494349454e545f42414c414e4345000000000000604482015290519081900360640190fd5b73ffffffffffffffffffffffffffffffffffffffff831660009081526020819052604090205482810110156105c357604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601060248201527f55494e543235365f4f564552464c4f5700000000000000000000000000000000604482015290519081900360640190fd5b336000818152602081815260408083208054879003905573ffffffffffffffffffffffffffffffffffffffff871680845292819020805487019055805186815290519293927fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef929181900390910190a350600192915050565b73ffffffffffffffffffffffffffffffffffffffff9182166000908152600160209081526040808320939094168252919091522054905600a165627a7a72305820203a592c9390a8a005821d7dffa1c27ae97bf827d8ef17cfee3a8a70776b22d90029"

packages/ethereum-types/src/index.ts

@@ -612,12 +612,12 @@ export interface EvmBytecodeOutput {
 }
 
 export interface DevdocOutput {
-    title: string;
-    author: string;
+    title?: string;
+    author?: string;
     methods: {
         [signature: string]: {
-            details: string;
-            params: {
+            details?: string;
+            params?: {
                 [name: string]: ParamDescription;
             };
             return?: string;

packages/sol-doc/src/sol_doc.ts

@@ -307,7 +307,10 @@ export class SolDoc {
     }
     private _genDocSection(compiledContract: StandardContractOutput, contractName: string): DocSection {
         const docSection: DocSection = {
-            comment: compiledContract.devdoc === undefined ? '' : compiledContract.devdoc.title,
+            comment:
+                compiledContract.devdoc === undefined || compiledContract.devdoc.title === undefined
+                    ? ''
+                    : compiledContract.devdoc.title,
             constructors: [],
             methods: [],
             properties: [],

python-packages/contract_artifacts/src/zero_ex/contract_artifacts/artifacts/ERC20Token.json

@@ -82,6 +82,53 @@
                 "type": "event"
             }
         ],
+        "devdoc": {
+            "methods": {
+                "allowance(address,address)": {
+                    "params": {
+                        "_owner": "The address of the account owning tokens",
+                        "_spender": "The address of the account able to transfer the tokens"
+                    },
+                    "return": "Amount of remaining tokens allowed to spent"
+                },
+                "approve(address,uint256)": {
+                    "details": "`msg.sender` approves `_spender` to spend `_value` tokens",
+                    "params": {
+                        "_spender": "The address of the account able to transfer the tokens",
+                        "_value": "The amount of wei to be approved for transfer"
+                    },
+                    "return": "Always true if the call has enough gas to complete execution"
+                },
+                "balanceOf(address)": {
+                    "details": "Query the balance of owner",
+                    "params": {
+                        "_owner": "The address from which the balance will be retrieved"
+                    },
+                    "return": "Balance of owner"
+                },
+                "totalSupply()": {
+                    "details": "Query total supply of token",
+                    "return": "Total supply of token"
+                },
+                "transfer(address,uint256)": {
+                    "details": "send `value` token to `to` from `msg.sender`",
+                    "params": {
+                        "_to": "The address of the recipient",
+                        "_value": "The amount of token to be transferred"
+                    },
+                    "return": "True if transfer was successful"
+                },
+                "transferFrom(address,address,uint256)": {
+                    "details": "send `value` token to `to` from `from` on the condition it is approved by `from`",
+                    "params": {
+                        "_from": "The address of the sender",
+                        "_to": "The address of the recipient",
+                        "_value": "The amount of token to be transferred"
+                    },
+                    "return": "True if transfer was successful"
+                }
+            }
+        },
         "evm": {
             "bytecode": {
                 "object": "0x608060405234801561001057600080fd5b506106a0806100206000396000f3006080604052600436106100775763ffffffff7c0100000000000000000000000000000000000000000000000000000000600035041663095ea7b3811461007c57806318160ddd146100c157806323b872dd146100e857806370a082311461011f578063a9059cbb1461014d578063dd62ed3e1461017e575b600080fd5b34801561008857600080fd5b506100ad73ffffffffffffffffffffffffffffffffffffffff600435166024356101b2565b604080519115158252519081900360200190f35b3480156100cd57600080fd5b506100d6610225565b60408051918252519081900360200190f35b3480156100f457600080fd5b506100ad73ffffffffffffffffffffffffffffffffffffffff6004358116906024351660443561022b565b34801561012b57600080fd5b506100d673ffffffffffffffffffffffffffffffffffffffff60043516610487565b34801561015957600080fd5b506100ad73ffffffffffffffffffffffffffffffffffffffff600435166024356104af565b34801561018a57600080fd5b506100d673ffffffffffffffffffffffffffffffffffffffff6004358116906024351661063c565b33600081815260016020908152604080832073ffffffffffffffffffffffffffffffffffffffff8716808552908352818420869055815186815291519394909390927f8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925928290030190a350600192915050565b60025490565b73ffffffffffffffffffffffffffffffffffffffff83166000908152602081905260408120548211156102bf57604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601a60248201527f45524332305f494e53554646494349454e545f42414c414e4345000000000000604482015290519081900360640190fd5b73ffffffffffffffffffffffffffffffffffffffff8416600090815260016020908152604080832033845290915290205482111561035e57604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601c60248201527f45524332305f494e53554646494349454e545f414c4c4f57414e434500000000604482015290519081900360640190fd5b73ffffffffffffffffffffffffffffffffffffffff831660009081526020819052604090205482810110156103f457604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601060248201527f55494e543235365f4f564552464c4f5700000000000000000000000000000000604482015290519081900360640190fd5b73ffffffffffffffffffffffffffffffffffffffff80841660008181526020818152604080832080548801905593881680835284832080548890039055600182528483203384528252918490208054879003905583518681529351929391927fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef9281900390910190a35060019392505050565b73ffffffffffffffffffffffffffffffffffffffff1660009081526020819052604090205490565b3360009081526020819052604081205482111561052d57604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601a60248201527f45524332305f494e53554646494349454e545f42414c414e4345000000000000604482015290519081900360640190fd5b73ffffffffffffffffffffffffffffffffffffffff831660009081526020819052604090205482810110156105c357604080517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601060248201527f55494e543235365f4f564552464c4f5700000000000000000000000000000000604482015290519081900360640190fd5b336000818152602081815260408083208054879003905573ffffffffffffffffffffffffffffffffffffffff871680845292819020805487019055805186815290519293927fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef929181900390910190a350600192915050565b73ffffffffffffffffffffffffffffffffffffffff9182166000908152600160209081526040808320939094168252919091522054905600a165627a7a72305820203a592c9390a8a005821d7dffa1c27ae97bf827d8ef17cfee3a8a70776b22d90029"