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 #1220 from ethereum/doc-updates

Browse Source 
Documentation updates
This commit is contained in:
chriseth 2016-10-19 16:15:33 +02:00 committed by GitHub
commit 3bcf0909af
8 changed files with 84 additions and 195 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/contracts.rst
View File

@ -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

4
docs/control-structures.rst
View File

@ -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

181
docs/frequently-asked-questions.rst
View File

@ -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?
=======================================

10
docs/index.rst
View File

@ -1,8 +1,12 @@
Solidity
========
Solidity is a high-level language whose syntax is similar to that of JavaScript
and it is designed to compile to code for the Ethereum Virtual Machine.
Solidity is a contract-oriented, high-level language whose syntax is similar to that of JavaScript
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>`_

2
docs/installing-solidity.rst
View File

@ -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

16
docs/introduction-to-smart-contracts.rst
View File

@ -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``,
it can still perform that operation using ``delegatecall`` or ``callcode``.
.. 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.

1
docs/miscellaneous.rst
View File

@ -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)

33
docs/types.rst
View File

@ -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