From 8a06000a307e7f2a72f9bfdc114d84fab8ad2ebf Mon Sep 17 00:00:00 2001 From: chriseth Date: Thu, 9 Aug 2018 21:10:53 +0200 Subject: Update documentation. --- docs/contracts.rst | 8 +-- docs/control-structures.rst | 6 +-- docs/style-guide.rst | 123 +++++++++++++++++++++++++++++++++----------- docs/types.rst | 2 +- 4 files changed, 100 insertions(+), 39 deletions(-) diff --git a/docs/contracts.rst b/docs/contracts.rst index 7cf715fa..ca15d814 100644 --- a/docs/contracts.rst +++ b/docs/contracts.rst @@ -137,16 +137,16 @@ Functions have to be specified as being ``external``, For state variables, ``external`` is not possible. ``external``: - External functions are part of the contract - interface, which means they can be called from other contracts and + External functions are part of the contract interface, + which means they can be called from other contracts and via transactions. An external function ``f`` cannot be called internally (i.e. ``f()`` does not work, but ``this.f()`` works). External functions are sometimes more efficient when they receive large arrays of data. ``public``: - Public functions are part of the contract - interface and can be either called internally or via + Public functions are part of the contract interface + and can be either called internally or via messages. For public state variables, an automatic getter function (see below) is generated. diff --git a/docs/control-structures.rst b/docs/control-structures.rst index 7efdc4e1..def75132 100644 --- a/docs/control-structures.rst +++ b/docs/control-structures.rst @@ -159,8 +159,8 @@ throws an exception or goes out of gas. .. warning:: Any interaction with another contract imposes a potential danger, especially - if the source code of the contract is not known in advance. The current - contract hands over control to the called contract and that may potentially + if the source code of the contract is not known in advance. The + current contract hands over control to the called contract and that may potentially do just about anything. Even if the called contract inherits from a known parent contract, the inheriting contract is only required to have a correct interface. The implementation of the contract, however, can be completely arbitrary and thus, @@ -293,7 +293,7 @@ These can then either be assigned to newly declared variables or to pre-existing function g() public { // Variables declared with type and assigned from the returned tuple, - // not all elements have to be specified (but the amount must match). + // not all elements have to be specified (but the number must match). (uint x, , uint y) = f(); // Common trick to swap values -- does not work for non-value storage types. (x, y) = (y, x); diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 53e126b4..d2de5287 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -52,31 +52,35 @@ Surround top level declarations in solidity source with two blank lines. Yes:: + pragma solidity ^0.4.0; + contract A { - ... + // ... } contract B { - ... + // ... } contract C { - ... + // ... } No:: + pragma solidity ^0.4.0; + contract A { - ... + // ... } contract B { - ... + // ... } contract C { - ... + // ... } Within a contract surround function declarations with a single blank line. @@ -85,30 +89,34 @@ Blank lines may be omitted between groups of related one-liners (such as stub fu Yes:: + pragma solidity ^0.4.0; + contract A { - function spam() public; - function ham() public; + function spam() public pure; + function ham() public pure; } contract B is A { - function spam() public { - ... + function spam() public pure { + // ... } - function ham() public { - ... + function ham() public pure { + // ... } } No:: + pragma solidity ^0.4.0; + contract A { - function spam() public { - ... + function spam() public pure { + // ... } - function ham() public { - ... + function ham() public pure { + // ... } } @@ -229,22 +237,24 @@ Import statements should always be placed at the top of the file. Yes:: - import "./Owned.sol"; + pragma solidity ^0.4.0; + import "./Owned.sol"; contract A { - ... + // ... } - contract B is Owned { - ... + // ... } No:: + pragma solidity ^0.4.0; + contract A { - ... + // ... } @@ -252,7 +262,7 @@ No:: contract B is Owned { - ... + // ... } Order of Functions @@ -273,13 +283,15 @@ Within a grouping, place the ``view`` and ``pure`` functions last. Yes:: + pragma solidity ^0.4.0; + contract A { constructor() public { - ... + // ... } function() external { - ... + // ... } // External functions @@ -303,13 +315,15 @@ Yes:: No:: + pragma solidity ^0.4.0; + contract A { // External functions // ... function() external { - ... + // ... } // Private functions @@ -319,7 +333,7 @@ No:: // ... constructor() public { - ... + // ... } // Internal functions @@ -397,6 +411,8 @@ should: Yes:: + pragma solidity ^0.4.0; + contract Coin { struct Bank { address owner; @@ -406,6 +422,8 @@ Yes:: No:: + pragma solidity ^0.4.0; + contract Coin { struct Bank { @@ -705,7 +723,25 @@ manner as modifiers if the function declaration is long or hard to read. Yes:: + pragma solidity ^0.4.0; + + // Base contracts just to make this compile + contract B { + constructor(uint) public { + } + } + contract C { + constructor(uint, uint) public { + } + } + contract D { + constructor(uint) public { + } + } + contract A is B, C, D { + uint x; + constructor(uint param1, uint param2, uint param3, uint param4, uint param5) B(param1) C(param2, param3) @@ -713,29 +749,50 @@ Yes:: public { // do something with param5 + x = param5; } } No:: + pragma solidity ^0.4.0; + + // Base contracts just to make this compile + contract B { + constructor(uint) public { + } + } + contract C { + constructor(uint, uint) public { + } + } + contract D { + constructor(uint) public { + } + } + contract A is B, C, D { + uint x; + constructor(uint param1, uint param2, uint param3, uint param4, uint param5) B(param1) C(param2, param3) D(param4) public { - // do something with param5 + x = param5; } } - contract A is B, C, D { + contract X is B, C, D { + uint x; + constructor(uint param1, uint param2, uint param3, uint param4, uint param5) B(param1) C(param2, param3) D(param4) public { - // do something with param5 + x = param5; } } @@ -875,6 +932,8 @@ As shown in the example below, if the contract name is `Congress` and the librar Yes:: + pragma solidity ^0.4.0; + // Owned.sol contract Owned { address public owner; @@ -897,11 +956,13 @@ Yes:: import "./Owned.sol"; contract Congress is Owned, TokenRecipient { - ... + //... } No:: + pragma solidity ^0.4.0; + // owned.sol contract owned { address public owner; @@ -924,7 +985,7 @@ No:: import "./owned.sol"; contract Congress is owned, tokenRecipient { - ... + //... } diff --git a/docs/types.rst b/docs/types.rst index 2cb85387..c216fd83 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -662,7 +662,7 @@ Allocating Memory Arrays Creating arrays with variable length in memory can be done using the ``new`` keyword. As opposed to storage arrays, it is **not** possible to resize memory arrays (e.g. by assigning to the ``.length`` member). You either have to calculate the required size in advance -or crete a new memory array and copy every element. +or create a new memory array and copy every element. :: -- cgit