Merge pull request #1220 from ethereum/doc-updates

Documentation updates

docs/contracts.rst

@@ -20,6 +20,9 @@ Contracts can be created "from outside" or from Solidity contracts.
 When a contract is created, its constructor (a function with the same
 name as the contract) is executed once.
 
+A constructor is optional. Only one constructor is allowed and this means
+overloading is not supported.
+
 From ``web3.js``, i.e. the JavaScript
 API, this is done as follows::
 
@@ -421,9 +424,9 @@ change by overriding).
 
 .. index:: ! constant
 
-**********
+************************
-Constants
+Constant State Variables
-**********
+************************
 
 State variables can be declared as constant (this is not yet implemented
 for array and struct types and not possible for mapping types).
@@ -442,6 +445,27 @@ for these variables and every occurrence is replaced by their constant value.
 
 The value expression can only contain integer arithmetics.
 
+******************
+Constant Functions
+******************
+
+Functions can be declared constant. These functions promise not to modify the state.
+
+::
+
+    pragma solidity ^0.4.0;
+
+    contract C {
+        function f(uint a, uint b) constant returns (uint) {
+            return a * (b + 42);
+        }
+    }
+
+.. note::
+  Accessor methods are marked constant.
+
+.. warning::
+  The compiler does not enforce yet that a constant method is not modifying state.
 
 .. index:: ! fallback function, function;fallback
 
@@ -976,7 +1000,7 @@ are all compiled as calls (``DELEGATECALL``) to an external
 contract/library. If you use libraries, take care that an
 actual external function call is performed.
 ``msg.sender``, ``msg.value`` and ``this`` will retain their values
-in this call, though (prior to Homestead, ``msg.sender`` and
+in this call, though (prior to Homestead, because of the use of `CALLCODE`, ``msg.sender`` and
 ``msg.value`` changed, though).
 
 The following example shows how to use memory types and

docs/control-structures.rst

@@ -7,7 +7,7 @@ Expressions and Control Structures
 Control Structures
 ===================
 
-Most of the control structures from C/JavaScript are available in Solidity
+Most of the control structures from C or JavaScript are available in Solidity
 except for ``switch`` and ``goto``. So
 there is: ``if``, ``else``, ``while``, ``for``, ``break``, ``continue``, ``return``, ``? :``, with
 the usual semantics known from C or JavaScript.
@@ -785,7 +785,7 @@ Conventions in Solidity
 
 In contrast to EVM assembly, Solidity knows types which are narrower than 256 bits,
 e.g. ``uint24``. In order to make them more efficient, most arithmetic operations just
-treat them as 256 bit numbers and the higher-order bits are only cleaned at the
+treat them as 256-bit numbers and the higher-order bits are only cleaned at the
 point where it is necessary, i.e. just shortly before they are written to memory
 or before comparisons are performed. This means that if you access such a variable
 from within inline assembly, you might have to manually clean the higher order bits

docs/frequently-asked-questions.rst

@@ -9,33 +9,12 @@ This list was originally compiled by `fivedogit <mailto:fivedogit@gmail.com>`_.
 Basic Questions
 ***************
 
-What is Solidity?
+Example contracts
 =================
 
-Solidity is the DEV-created (i.e. Ethereum Foundation-created),
-Javascript-inspired language that can be used to create smart contracts
-on the Ethereum blockchain. There are other
-languages you can use as well (LLL, Serpent, etc). The main points in
-favour of Solidity is that it is statically typed and offers many
-advanced features like inheritance, libraries, complex
-user-defined types and a bytecode optimizer.
-
-Solidity contracts can be compiled a few different ways (see below) and the
-resulting output can be cut/pasted into a geth console to deploy them to the
-Ethereum blockchain.
-
 There are some `contract examples <https://github.com/fivedogit/solidity-baby-steps/tree/master/contracts/>`_ by fivedogit and
 there should be a `test contract <https://github.com/ethereum/solidity/blob/develop/test/libsolidity/SolidityEndToEndTest.cpp>`_ for every single feature of Solidity.
 
-How do I compile contracts?
-===========================
-
-Probably the fastest way is the `online compiler <https://ethereum.github.io/browser-solidity/>`_.
-
-You can also use the ``solc`` binary which comes with cpp-ethereum to compile
-contracts or an emerging option is to use Mix, the IDE.
-
-
 Create and publish the most basic contract possible
 ===================================================
 
@@ -71,13 +50,6 @@ several blockchain explorers.
 Contracts on the blockchain should have their original source
 code published if they are to be used by third parties.
 
-Does ``selfdestruct()`` free up space in the blockchain?
-========================================================
-
-It removes the contract bytecode and storage from the current block
-into the future, but since the blockchain stores every single block (i.e.
-all history), this will not actually free up space on full/archive nodes.
-
 Create a contract that can be killed and return funds
 =====================================================
 
@@ -113,32 +85,6 @@ Use a non-constant function (req ``sendTransaction``) to increment a variable in
 
 See `value_incrementer.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/20_value_incrementer.sol>`_.
 
-Get contract address in Solidity
-================================
-
-Short answer: The global variable ``this`` is the contract address.
-
-See `basic_info_getter <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/15_basic_info_getter.sol>`_.
-
-Long answer: ``this`` is a variable representing the current contract.
-Its type is the type of the contract. Since any contract type basically inherits from the
-``address`` type, ``this`` is always convertible to ``address`` and in this case contains
-its own address.
-
-What is the difference between a function marked ``constant`` and one that is not?
-==================================================================================
-
-``constant`` functions can perform some action and return a value, but cannot
-change state (this is not yet enforced by the compiler). In other words, a
-constant function cannot save or update any variables within the contract or wider
-blockchain. These functions are called using ``c.someFunction(...)`` from
-geth or any other web3.js environment.
-
-"non-constant" functions (those lacking the ``constant`` specifier) must be called
-with ``c.someMethod.sendTransaction({from:eth.accounts[x], gas: 1000000});``
-That is, because they can change state, they have to have a gas
-payment sent along to get the work done.
-
 Get a contract to return its funds to you (not using ``selfdestruct(...)``).
 ============================================================================
 
@@ -146,52 +92,6 @@ This example demonstrates how to send funds from a contract to an address.
 
 See `endowment_retriever <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/30_endowment_retriever.sol>`_.
 
-What is a ``mapping`` and how do we use them?
-=============================================
-
-A mapping is very similar to a K->V hashmap.
-If you have a state variable of type ``mapping (string -> uint) x;``, then you can
-access the value by ``x["somekeystring"]``.
-
-How can I get the length of a ``mapping``?
-==========================================
-
-Mappings are a rather low-level data structure. It does not store the keys
-and it is not possible to know which or how many values are "set". Actually,
-all values to all possible keys are set by default, they are just
-initialised with the zero value.
-
-In this sense, the attribute ``length`` for a mapping does not really apply.
-
-If you want to have a "sized mapping", you can use the iterable mapping
-(see below) or just a dynamically-sized array of structs.
-
-Are ``mapping``'s iterable?
-===========================
-
-Mappings themselves are not iterable, but you can use a higher-level
-datastructure on top of it, for example the `iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_.
-
-Can I put arrays inside of a ``mapping``? How do I make a ``mapping`` of a ``mapping``?
-=======================================================================================
-
-Mappings are already syntactically similar to arrays as they are, therefore it doesn't make much sense to store an array in them. Rather what you should do is create a mapping of a mapping.
-
-An example of this would be::
-
-    contract C {
-        struct myStruct {
-            uint someNumber;
-            string someString;
-        }
-
-        mapping(uint => mapping(string => myStruct)) myDynamicMapping;
-
-        function storeInMapping() {
-            myDynamicMapping[1]["Foo"] = myStruct(2, "Bar");
-        }
-    }
-
 Can you return an array or a ``string`` from a solidity function call?
 ======================================================================
 
@@ -223,61 +123,6 @@ Example::
         }
     }
 
-What are ``event``'s and why do we need them?
-=============================================
-
-Let us suppose that you need a contract to alert the outside world when
-something happens. The contract can fire an event, which can be listened to
-from web3 (inside geth or a web application). The main advantage of events
-is that they are stored in a special way on the blockchain so that it
-is very easy to search for them.
-
-What are the different function visibilities?
-=============================================
-
-The visibility specifiers do not only change the visibility but also
-the way functions can be called. In general, functions in the
-same contract can also be called internally (which is cheaper
-and allows for memory types to be passed by reference). This
-is done if you just use ``f(1,2)``. If you use ``this.f(1,2)``
-or ``otherContract.f(1,2)``, the function is called externally.
-
-Internal function calls have the advantage that you can use
-all Solidity types as parameters, but you have to stick to the
-simpler ABI types for external calls.
-
-* ``external``: all, only externally
-
-* ``public``: all (this is the default), externally and internally
-
-* ``internal``: only this contract and contracts deriving from it, only internally
-
-* ``private``: only this contract, only internally
-
-
-Do contract constructors have to be publicly visible?
-=====================================================
-
-You can use the visibility specifiers, but they do not yet have any effect.
-The constructor is removed from the contract code once it is deployed,
-
-Can a contract have multiple constructors?
-==========================================
-
-No, a contract can have only one constructor.
-
-More specifically, it can only have one function whose name matches
-that of the constructor.
-
-Having multiple constructors with different number of arguments
-or argument types, as it is possible in other languages
-is not allowed in Solidity.
-
-Is a constructor required?
-==========================
-
-No. If there is no constructor, a generic one without arguments and no actions will be used.
-
 Are timestamps (``now,`` ``block.timestamp``) reliable?
 =======================================================
 
@@ -363,14 +208,6 @@ Examples::
         C c = new C();
     }
 
-What is the ``modifier`` keyword?
-=================================
-
-Modifiers are a way to prepend or append code to a function in order
-to add guards, initialisation or cleanup functionality in a concise way.
-
-For examples, see the `features.sol <https://github.com/ethereum/dapp-bin/blob/master/library/features.sol>`_.
-
 How do structs work?
 ====================
 
@@ -590,12 +427,6 @@ The correct way to do this is the following::
         }
     }
 
-Can a regular (i.e. non-contract) ethereum account be closed permanently like a contract can?
-=============================================================================================
-
-No. Non-contract accounts "exist" as long as the private key is known by
-someone or can be generated in some way.
-
 What is the difference between ``bytes`` and ``byte[]``?
 ========================================================
 
@@ -641,16 +472,6 @@ Use the constructor. Anything inside it will be executed when the contract is fi
 
 See `replicator.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/50_replicator.sol>`_.
 
-Can a contract create another contract?
-=======================================
-
-Yes, see `replicator.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/50_replicator.sol>`_.
-
-Note that the full code of the created contract has to be included in the creator contract.
-This also means that cyclic creations are not possible (because the contract would have
-to contain its own code) - at least not in a general way.
-
-
 How do you create 2-dimensional arrays?
 =======================================
 

docs/index.rst

@@ -1,8 +1,12 @@
 Solidity
 ========
 
-Solidity is a high-level language whose syntax is similar to that of JavaScript
+Solidity is a contract-oriented, high-level language whose syntax is similar to that of JavaScript
-and it is designed to compile to code for the Ethereum Virtual Machine.
+and it is designed to target the Ethereum Virtual Machine.
+
+Solidity is statically typed, supports inheritance, libraries and complex
+user-defines types among other features.
+
 As you will see, it is possible to create contracts for voting,
 crowdfunding, blind auctions, multi-signature wallets and more.
 
@@ -16,7 +20,7 @@ Useful links
 
 * `Ethereum <https://ethereum.org>`_
 
-* `Changelog <https://github.com/ethereum/wiki/wiki/Solidity-Changelog>`_
+* `Changelog <https://github.com/ethereum/solidity/blob/develop/Changelog.md>`_
 
 * `Story Backlog <https://www.pivotaltracker.com/n/projects/1189488>`_
 

docs/installing-solidity.rst

@@ -9,7 +9,7 @@ Installing Solidity
 Versioning
 ==========
 
-Solidity versions follow `semantic versioning <https://semver.org>` and in addition to
+Solidity versions follow `semantic versioning <https://semver.org>`_ and in addition to
 releases, **nightly development builds** are also made available.  The nightly builds
 are not guaranteed to be working and despite best efforts they might contain undocumented
 and/or broken changes. We recommend to use the latest release. Package installers below

docs/introduction-to-smart-contracts.rst

@@ -455,13 +455,19 @@ receives the address of the new contract on the stack.
 
 .. index:: selfdestruct
 
-``selfdestruct``
+Self-destruct
-================
+=============
 
 The only possibility that code is removed from the blockchain is
 when a contract at that address performs the ``selfdestruct`` operation.
 The remaining Ether stored at that address is sent to a designated
-target and then the storage and code is removed.
+target and then the storage and code is removed from the state.
 
-Note that even if a contract's code does not contain a call to ``selfdestruct``,
+.. warning:: Even if a contract's code does not contain a call to ``selfdestruct``,
   it can still perform that operation using ``delegatecall`` or ``callcode``.
+
+.. note:: The pruning of old contracts may or may not be implemented by Ethereum
+  clients. Additionally, archive nodes could choose to keep the contract storage
+  and code indefinitely.
+
+.. note:: Currently **external accounts** cannot be removed from the state.

docs/miscellaneous.rst

@@ -61,6 +61,7 @@ Layout in Memory
 ****************
 
 Solidity reserves three 256-bit slots:
+
 -  0 - 64: scratch space for hashing methods
 - 64 - 96: currently allocated memory size (aka. free memory pointer)
 

docs/types.rst

@@ -371,6 +371,9 @@ So ``bytes`` should always be preferred over ``byte[]`` because it is cheaper.
     that you are accessing the low-level bytes of the UTF-8 representation,
     and not the individual characters!
 
+It is possible to mark arrays ``public`` and have Solidity create an accessor.
+The numeric index will become a required parameter for the accessor.
+
 .. index:: ! array;allocating, new
 
 Allocating Memory Arrays
@@ -617,6 +620,36 @@ Because of this, mappings do not have a length or a concept of a key or value be
 Mappings are only allowed for state variables (or as storage reference types
 in internal functions).
 
+It is possible to mark mappings ``public`` and have Solidity create an accessor.
+The ``_KeyType`` will become a required parameter for the accessor and it will
+return ``_ValueType``.
+
+The ``_ValueType`` can be a mapping too. The accessor will have one parameter
+for each ``_KeyType``, recursively.
+
+::
+
+    pragma solidity ^0.4.0;
+
+    contract MappingExample {
+        mapping(address => uint) public balances;
+
+        function update(uint newBalance) {
+            balances[msg.sender] = newBalance;
+        }
+    }
+
+    contract MappingUser {
+        function f() returns (uint) {
+            return MappingExample(<address>).balances(this);
+        }
+    }
+
+
+.. note::
+  Mappings are not iterable, but it is possible to implement a data structure on top of them.
+  For an example, see `iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_.
+
 .. index:: assignment, ! delete, lvalue
 
 Operators Involving LValues