cerc-io/solidity
10
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #3152 from ethereum/docs-tests

Browse Source 
Ensure each code snippet in the docs can be extracted for tests
This commit is contained in:
Alex Beregszaszi 2017-11-22 04:59:28 +00:00 committed by GitHub
commit be34b574bf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 107 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/abi-spec.rst
View File

@ -330,15 +330,15 @@ For example,
::
pragma solidity ^0.4.0;
pragma solidity ^0.4.0;
contract Test {
function Test(){ b = 0x12345678901234567890123456789012; }
event Event(uint indexed a, bytes32 b);
event Event2(uint indexed a, bytes32 b);
function foo(uint a) { Event(a, b); }
bytes32 b;
}
contract Test {
function Test(){ b = 0x12345678901234567890123456789012; }
event Event(uint indexed a, bytes32 b);
event Event2(uint indexed a, bytes32 b);
function foo(uint a) { Event(a, b); }
bytes32 b;
}
would result in the JSON:
@ -377,11 +377,11 @@ As an example, the code
::
contract Test {
struct S { uint a; uint[] b; T[] c; }
struct T { uint x; uint y; }
function f(S s, T t, uint a) { }
}
contract Test {
struct S { uint a; uint[] b; T[] c; }
struct T { uint x; uint y; }
function f(S s, T t, uint a) { }
}
would result in the JSON:

40
docs/contracts.rst
View File

@ -198,7 +198,6 @@ In the following example, ``D``, can call ``c.getData()`` to retrieve the value
function compute(uint a, uint b) internal returns (uint) { return a+b; }
}
contract D {
function readData() {
C c = new C();
@ -209,7 +208,6 @@ In the following example, ``D``, can call ``c.getData()`` to retrieve the value
}
}
contract E is C {
function g() {
C c = new C();
@ -238,7 +236,6 @@ be done at declaration.
uint public data = 42;
}
contract Caller {
C c = new C();
function f() {
@ -321,7 +318,6 @@ inheritable properties of contracts and may be overridden by derived contracts.
}
}
contract mortal is owned {
// This contract inherits the "onlyOwner"-modifier from
// "owned" and applies it to the "close"-function, which
@ -332,7 +328,6 @@ inheritable properties of contracts and may be overridden by derived contracts.
}
}
contract priced {
// Modifiers can receive arguments:
modifier costs(uint price) {
@ -342,7 +337,6 @@ inheritable properties of contracts and may be overridden by derived contracts.
}
}
contract Register is priced, owned {
mapping (address => bool) registeredAddresses;
uint price;
@ -570,7 +564,6 @@ Please ensure you test your fallback function thoroughly to ensure the execution
function() payable { }
}
contract Caller {
function callTest(Test test) {
test.call(0xabcdef01); // hash does not exist
@ -687,12 +680,19 @@ as topics. The event call above can be performed in the same way as
::
log3(
msg.value,
0x50cb9fe53daa9737b786ab3646f04d0150dc50ef4e75f59509d83667ad5adb20,
msg.sender,
_id
);
pragma solidity ^0.4.10;
contract C {
function f() {
bytes32 _id = 0x420042;
log3(
bytes32(msg.value),
bytes32(0x50cb9fe53daa9737b786ab3646f04d0150dc50ef4e75f59509d83667ad5adb20),
bytes32(msg.sender),
_id
);
}
}
where the long hexadecimal number is equal to
``keccak256("Deposit(address,hash256,uint256)")``, the signature of the event.
@ -734,7 +734,6 @@ Details are given in the following example.
address owner;
}
// Use "is" to derive from another contract. Derived
// contracts can access all non-private members including
// internal functions and state variables. These cannot be
@ -745,7 +744,6 @@ Details are given in the following example.
}
}
// These abstract contracts are only provided to make the
// interface known to the compiler. Note the function
// without body. If a contract does not implement all
@ -754,13 +752,11 @@ Details are given in the following example.
function lookup(uint id) returns (address adr);
}
contract NameReg {
function register(bytes32 name);
function unregister();
}
// Multiple inheritance is possible. Note that "owned" is
// also a base class of "mortal", yet there is only a single
// instance of "owned" (as for virtual inheritance in C++).
@ -786,7 +782,6 @@ Details are given in the following example.
}
}
// If a constructor takes an argument, it needs to be
// provided in the header (or modifier-invocation-style at
// the constructor of the derived contract (see below)).
@ -821,12 +816,10 @@ seen in the following example::
function kill() { /* do cleanup 1 */ mortal.kill(); }
}
contract Base2 is mortal {
function kill() { /* do cleanup 2 */ mortal.kill(); }
}
contract Final is Base1, Base2 {
}
@ -848,7 +841,6 @@ derived override, but this function will bypass
}
}
contract Base1 is mortal {
function kill() { /* do cleanup 1 */ super.kill(); }
}
@ -858,7 +850,6 @@ derived override, but this function will bypass
function kill() { /* do cleanup 2 */ super.kill(); }
}
contract Final is Base2, Base1 {
}
@ -888,7 +879,6 @@ the base constructors. This can be done in two ways::
function Base(uint _x) { x = _x; }
}
contract Derived is Base(7) {
function Derived(uint _y) Base(_y * _y) {
}
@ -1081,7 +1071,6 @@ more advanced example to implement a set).
}
}
contract C {
Set.Data knownValues;
@ -1157,7 +1146,6 @@ custom types without the overhead of external function calls:
}
}
contract C {
using BigInt for BigInt.bigint;
@ -1250,7 +1238,6 @@ Let us rewrite the set example from the
}
}
contract C {
using Set for Set.Data; // this is the crucial change
Set.Data knownValues;
@ -1276,7 +1263,6 @@ It is also possible to extend elementary types in that way::
}
}
contract C {
using Search for uint[];
uint[] data;

22
docs/control-structures.rst
View File

@ -194,7 +194,7 @@ Omitted Function Parameter Names
--------------------------------
The names of unused parameters (especially return parameters) can be omitted.
Those names will still be present on the stack, but they are inaccessible.
Those parameters will still be present on the stack, but they are inaccessible.
::
@ -363,15 +363,19 @@ As a result, the following code is illegal and cause the compiler to throw an er
In addition to this, if a variable is declared, it will be initialized at the beginning of the function to its default value.
As a result, the following code is legal, despite being poorly written::
function foo() returns (uint) {
// baz is implicitly initialized as 0
uint bar = 5;
if (true) {
bar += baz;
} else {
uint baz = 10;// never executes
pragma solidity ^0.4.0;
contract C {
function foo() returns (uint) {
// baz is implicitly initialized as 0
uint bar = 5;
if (true) {
bar += baz;
} else {
uint baz = 10;// never executes
}
return bar;// returns 5
}
return bar;// returns 5
}
.. index:: ! exception, ! throw, ! assert, ! require, ! revert

48
docs/security-considerations.rst
View File

@ -55,18 +55,18 @@ complete contract):
::
pragma solidity ^0.4.0;
pragma solidity ^0.4.0;
// THIS CONTRACT CONTAINS A BUG - DO NOT USE
contract Fund {
/// Mapping of ether shares of the contract.
mapping(address => uint) shares;
/// Withdraw your share.
function withdraw() {
if (msg.sender.send(shares[msg.sender]))
shares[msg.sender] = 0;
}
}
// THIS CONTRACT CONTAINS A BUG - DO NOT USE
contract Fund {
/// Mapping of ether shares of the contract.
mapping(address => uint) shares;
/// Withdraw your share.
function withdraw() {
if (msg.sender.send(shares[msg.sender]))
shares[msg.sender] = 0;
}
}
The problem is not too serious here because of the limited gas as part
of ``send``, but it still exposes a weakness: Ether transfer always
@ -79,18 +79,18 @@ outlined further below:
::
pragma solidity ^0.4.11;
pragma solidity ^0.4.11;
contract Fund {
/// Mapping of ether shares of the contract.
mapping(address => uint) shares;
/// Withdraw your share.
function withdraw() {
var share = shares[msg.sender];
shares[msg.sender] = 0;
msg.sender.transfer(share);
}
}
contract Fund {
/// Mapping of ether shares of the contract.
mapping(address => uint) shares;
/// Withdraw your share.
function withdraw() {
var share = shares[msg.sender];
shares[msg.sender] = 0;
msg.sender.transfer(share);
}
}
Note that re-entrancy is not only an effect of Ether transfer but of any
function call on another contract. Furthermore, you also have to take
@ -179,7 +179,9 @@ Never use tx.origin for authorization. Let's say you have a wallet contract like
}
}
Now someone tricks you into sending ether to the address of this attack wallet::
Now someone tricks you into sending ether to the address of this attack wallet:
::
pragma solidity ^0.4.11;

86
docs/structure-of-a-contract.rst
View File

@ -20,12 +20,12 @@ State variables are values which are permanently stored in contract storage.
::
pragma solidity ^0.4.0;
pragma solidity ^0.4.0;
contract SimpleStorage {
uint storedData; // State variable
// ...
}
contract SimpleStorage {
uint storedData; // State variable
// ...
}
See the :ref:`types` section for valid state variable types and
:ref:`visibility-and-getters` for possible choices for
@ -40,13 +40,13 @@ Functions are the executable units of code within a contract.
::
pragma solidity ^0.4.0;
pragma solidity ^0.4.0;
contract SimpleAuction {
function bid() payable { // Function
// ...
}
}
contract SimpleAuction {
function bid() payable { // Function
// ...
}
}
:ref:`function-calls` can happen internally or externally
and have different levels of visibility (:ref:`visibility-and-getters`)
@ -62,20 +62,20 @@ Function modifiers can be used to amend the semantics of functions in a declarat
::
pragma solidity ^0.4.11;
pragma solidity ^0.4.11;
contract Purchase {
address public seller;
contract Purchase {
address public seller;
modifier onlySeller() { // Modifier
require(msg.sender == seller);
_;
}
modifier onlySeller() { // Modifier
require(msg.sender == seller);
_;
}
function abort() onlySeller { // Modifier usage
// ...
}
}
function abort() onlySeller { // Modifier usage
// ...
}
}
.. _structure-events:
@ -86,16 +86,16 @@ Events are convenience interfaces with the EVM logging facilities.
::
pragma solidity ^0.4.0;
pragma solidity ^0.4.0;
contract SimpleAuction {
event HighestBidIncreased(address bidder, uint amount); // Event
contract SimpleAuction {
event HighestBidIncreased(address bidder, uint amount); // Event
function bid() payable {
// ...
HighestBidIncreased(msg.sender, msg.value); // Triggering event
}
}
function bid() payable {
// ...
HighestBidIncreased(msg.sender, msg.value); // Triggering event
}
}
See :ref:`events` in contracts section for information on how events are declared
and can be used from within a dapp.
@ -110,16 +110,16 @@ Structs are custom defined types that can group several variables (see
::
pragma solidity ^0.4.0;
pragma solidity ^0.4.0;
contract Ballot {
struct Voter { // Struct
uint weight;
bool voted;
address delegate;
uint vote;
}
}
contract Ballot {
struct Voter { // Struct
uint weight;
bool voted;
address delegate;
uint vote;
}
}
.. _structure-enum-types:
@ -131,8 +131,8 @@ Enums can be used to create custom types with a finite set of values (see
::
pragma solidity ^0.4.0;
pragma solidity ^0.4.0;
contract Purchase {
enum State { Created, Locked, Inactive } // Enum
}
contract Purchase {
enum State { Created, Locked, Inactive } // Enum
}