mirror of
https://github.com/ethereum/solidity
synced 2023-10-03 13:03:40 +00:00
docs: fix formatting errors and style inconsistencies
This commit is contained in:
iamdefinitelyahuman
parent
c59854c4bb
commit
d59706e5f5
@ -195,7 +195,7 @@ In addition to the list of state modifying statements explained above, the follo
|
||||
}
|
||||
}
|
||||
|
||||
Pure functions are able to use the `revert()` and `require()` functions to revert
|
||||
Pure functions are able to use the ``revert()`` and ``require()`` functions to revert
|
||||
potential state changes when an :ref:`error occurs <assert-and-require>`.
|
||||
|
||||
Reverting a state change is not considered a "state modification", as only changes to the
|
||||
@ -235,9 +235,9 @@ A contract can have at most one ``receive`` function, declared using
|
||||
``receive() external payable { ... }``
|
||||
(without the ``function`` keyword).
|
||||
This function cannot have arguments, cannot return anything and must have
|
||||
``external`` visibility and ``payable`` state mutability. It is executed on a
|
||||
``external`` visibility and ``payable`` state mutability. It is executed on a
|
||||
call to the contract with empty calldata. This is the function that is executed
|
||||
on plain Ether transfers (e.g. via `.send()` or `.transfer()`). If no such
|
||||
on plain Ether transfers (e.g. via ``.send()`` or ``.transfer()``). If no such
|
||||
function exists, but a payable :ref:`fallback function <fallback-function>`
|
||||
exists, the fallback function will be called on a plain Ether transfer. If
|
||||
neither a receive Ether nor a payable fallback function is present, the
|
||||
@ -245,7 +245,7 @@ contract cannot receive Ether through regular transactions and throws an
|
||||
exception.
|
||||
|
||||
In the worst case, the fallback function can only rely on 2300 gas being
|
||||
available (for example when `send` or `transfer` is used), leaving little
|
||||
available (for example when ``send`` or ``transfer`` is used), leaving little
|
||||
room to perform other operations except basic logging. The following operations
|
||||
will consume more gas than the 2300 gas stipend:
|
||||
|
||||
@ -265,7 +265,7 @@ will consume more gas than the 2300 gas stipend:
|
||||
|
||||
.. warning::
|
||||
A contract without a receive Ether function can receive Ether as a
|
||||
recipient of a `coinbase transaction` (aka `miner block reward`)
|
||||
recipient of a *coinbase transaction* (aka *miner block reward*)
|
||||
or as a destination of a ``selfdestruct``.
|
||||
|
||||
A contract cannot react to such Ether transfers and thus also
|
||||
|
||||
@ -16,7 +16,7 @@ Functions have to be specified as being ``external``,
|
||||
``public``, ``internal`` or ``private``.
|
||||
For state variables, ``external`` is not possible.
|
||||
|
||||
``external``:
|
||||
``external``
|
||||
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
|
||||
@ -25,18 +25,18 @@ For state variables, ``external`` is not possible.
|
||||
they receive large arrays of data, because the data
|
||||
is not copied from calldata to memory.
|
||||
|
||||
``public``:
|
||||
``public``
|
||||
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.
|
||||
|
||||
``internal``:
|
||||
``internal``
|
||||
Those functions and state variables can only be
|
||||
accessed internally (i.e. from within the current contract
|
||||
or contracts deriving from it), without using ``this``.
|
||||
|
||||
``private``:
|
||||
``private``
|
||||
Private functions and state variables are only
|
||||
visible for the contract they are defined in and not in
|
||||
derived contracts.
|
||||
|
||||
@ -454,7 +454,7 @@ The recipient should verify each message using the following process:
|
||||
|
||||
We'll use the `ethereumjs-util <https://github.com/ethereumjs/ethereumjs-util>`_
|
||||
library to write this verification. The final step can be done a number of ways,
|
||||
and we use JavaScript. The following code borrows the `constructMessage` function from the signing **JavaScript code** above:
|
||||
and we use JavaScript. The following code borrows the ``constructMessage`` function from the signing **JavaScript code** above:
|
||||
|
||||
::
|
||||
|
||||
|
||||
@ -35,11 +35,11 @@ or if you require more compilation options.
|
||||
npm / Node.js
|
||||
=============
|
||||
|
||||
Use `npm` for a convenient and portable way to install `solcjs`, a Solidity compiler. The
|
||||
Use ``npm`` for a convenient and portable way to install ``solcjs``, a Solidity compiler. The
|
||||
`solcjs` program has fewer features than the ways to access the compiler described
|
||||
further down this page. The
|
||||
:ref:`commandline-compiler` documentation assumes you are using
|
||||
the full-featured compiler, `solc`. The usage of `solcjs` is documented inside its own
|
||||
the full-featured compiler, ``solc``. The usage of ``solcjs`` is documented inside its own
|
||||
`repository <https://github.com/ethereum/solc-js>`_.
|
||||
|
||||
Note: The solc-js project is derived from the C++
|
||||
@ -53,10 +53,10 @@ Please refer to the solc-js repository for instructions.
|
||||
|
||||
.. note::
|
||||
|
||||
The commandline executable is named `solcjs`.
|
||||
The commandline executable is named ``solcjs``.
|
||||
|
||||
The comandline options of `solcjs` are not compatible with `solc` and tools (such as `geth`)
|
||||
expecting the behaviour of `solc` will not work with `solcjs`.
|
||||
The comandline options of ``solcjs`` are not compatible with ``solc`` and tools (such as ``geth``)
|
||||
expecting the behaviour of ``solc`` will not work with ``solcjs``.
|
||||
|
||||
Docker
|
||||
======
|
||||
|
||||
@ -323,7 +323,7 @@ Every account has a persistent key-value store mapping 256-bit words to 256-bit
|
||||
words called **storage**.
|
||||
|
||||
Furthermore, every account has a **balance** in
|
||||
Ether (in "Wei" to be exact, `1 ether` is `10**18 wei`) which can be modified by sending transactions that
|
||||
Ether (in "Wei" to be exact, ``1 ether`` is ``10**18 wei``) which can be modified by sending transactions that
|
||||
include Ether.
|
||||
|
||||
.. index:: ! transaction
|
||||
@ -520,9 +520,9 @@ idea, but it is potentially dangerous, as if someone sends Ether to removed
|
||||
contracts, the Ether is forever lost.
|
||||
|
||||
.. warning::
|
||||
Even if a contract is removed by "selfdestruct", it is still part of the
|
||||
Even if a contract is removed by ``selfdestruct``, it is still part of the
|
||||
history of the blockchain and probably retained by most Ethereum nodes.
|
||||
So using "selfdestruct" is not the same as deleting data from a hard disk.
|
||||
So using ``selfdestruct`` is not the same as deleting data from a hard disk.
|
||||
|
||||
.. note::
|
||||
Even if a contract's code does not contain a call to ``selfdestruct``,
|
||||
|
||||
@ -73,8 +73,8 @@ Tags
|
||||
|
||||
All tags are optional. The following table explains the purpose of each
|
||||
NatSpec tag and where it may be used. As a special case, if no tags are
|
||||
used then the Solidity compiler will interpret a `///` or `/**` comment
|
||||
in the same way as if it were tagged with `@notice`.
|
||||
used then the Solidity compiler will interpret a ``///`` or ``/**`` comment
|
||||
in the same way as if it were tagged with ``@notice``.
|
||||
|
||||
=========== =============================================================================== =============================
|
||||
Tag Context
|
||||
|
||||
@ -24,8 +24,11 @@ solidity code. The goal of this guide is *consistency*. A quote from python's
|
||||
`pep8 <https://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds>`_
|
||||
captures this concept well.
|
||||
|
||||
.. note::
|
||||
|
||||
A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important.
|
||||
But most importantly: know when to be inconsistent -- sometimes the style guide just doesn't apply. When in doubt, use your best judgement. Look at other examples and decide what looks best. And don't hesitate to ask!
|
||||
|
||||
But most importantly: **know when to be inconsistent** -- sometimes the style guide just doesn't apply. When in doubt, use your best judgement. Look at other examples and decide what looks best. And don't hesitate to ask!
|
||||
|
||||
|
||||
***********
|
||||
@ -383,8 +386,7 @@ No::
|
||||
|
||||
function spam(uint i , Coin coin) public ;
|
||||
|
||||
More than one space around an assignment or other operator to align with
|
||||
another:
|
||||
More than one space around an assignment or other operator to align with another:
|
||||
|
||||
Yes::
|
||||
|
||||
@ -996,7 +998,7 @@ Contract and Library Names
|
||||
* Contract and library names should also match their filenames.
|
||||
* If a contract file includes multiple contracts and/or libraries, then the filename should match the *core contract*. This is not recommended however if it can be avoided.
|
||||
|
||||
As shown in the example below, if the contract name is `Congress` and the library name is `Owned`, then their associated filenames should be `Congress.sol` and `Owned.sol`.
|
||||
As shown in the example below, if the contract name is ``Congress`` and the library name is ``Owned``, then their associated filenames should be ``Congress.sol`` and ``Owned.sol``.
|
||||
|
||||
Yes::
|
||||
|
||||
@ -1132,8 +1134,8 @@ Solidity contracts can have a form of comments that are the basis of the
|
||||
Ethereum Natural Language Specification Format.
|
||||
|
||||
Add comments above functions or contracts following `doxygen <http://www.doxygen.nl>`_ notation
|
||||
of one or multiple lines starting with `///` or a
|
||||
multiline comment starting with `/**` and ending with `*/`.
|
||||
of one or multiple lines starting with ``///`` or a
|
||||
multiline comment starting with ``/**`` and ending with ``*/``.
|
||||
|
||||
For example, the contract from `a simple smart contract <simple-smart-contract>`_ with the comments
|
||||
added looks like the one below::
|
||||
|
||||
@ -16,7 +16,7 @@ operators. For a quick reference of the various operators, see :ref:`order`.
|
||||
The concept of "undefined" or "null" values does not exist in Solidity, but newly
|
||||
declared variables always have a :ref:`default value<default-value>` dependent
|
||||
on its type. To handle any unexpected values, you should use the :ref:`revert function<assert-and-require>` to revert the whole transaction, or return a
|
||||
tuple with a second `bool` value denoting success.
|
||||
tuple with a second ``bool`` value denoting success.
|
||||
|
||||
.. include:: types/value-types.rst
|
||||
|
||||
@ -26,4 +26,4 @@ tuple with a second `bool` value denoting success.
|
||||
|
||||
.. include:: types/operators.rst
|
||||
|
||||
.. include:: types/conversion.rst
|
||||
.. include:: types/conversion.rst
|
||||
|
||||
@ -332,7 +332,7 @@ the :ref:`address type<address>`.
|
||||
Before version 0.5.0, contracts directly derived from the address type
|
||||
and there was no distinction between ``address`` and ``address payable``.
|
||||
|
||||
If you declare a local variable of contract type (`MyContract c`), you can call
|
||||
If you declare a local variable of contract type (``MyContract c``), you can call
|
||||
functions on that contract. Take care to assign it from somewhere that is the
|
||||
same contract type.
|
||||
|
||||
|
||||
@ -140,15 +140,19 @@ Error Handling
|
||||
See the dedicated section on :ref:`assert and require<assert-and-require>` for
|
||||
more details on error handling and when to use which function.
|
||||
|
||||
``assert(bool condition)``:
|
||||
``assert(bool condition)``
|
||||
causes an invalid opcode and thus state change reversion if the condition is not met - to be used for internal errors.
|
||||
``require(bool condition)``:
|
||||
|
||||
``require(bool condition)``
|
||||
reverts if the condition is not met - to be used for errors in inputs or external components.
|
||||
``require(bool condition, string memory message)``:
|
||||
|
||||
``require(bool condition, string memory message)``
|
||||
reverts if the condition is not met - to be used for errors in inputs or external components. Also provides an error message.
|
||||
``revert()``:
|
||||
|
||||
``revert()``
|
||||
abort execution and revert state changes
|
||||
``revert(string memory reason)``:
|
||||
|
||||
``revert(string memory reason)``
|
||||
abort execution and revert state changes, providing an explanatory string
|
||||
|
||||
.. index:: keccak256, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography,
|
||||
@ -156,32 +160,32 @@ more details on error handling and when to use which function.
|
||||
Mathematical and Cryptographic Functions
|
||||
----------------------------------------
|
||||
|
||||
``addmod(uint x, uint y, uint k) returns (uint)``:
|
||||
``addmod(uint x, uint y, uint k) returns (uint)``
|
||||
compute ``(x + y) % k`` where the addition is performed with arbitrary precision and does not wrap around at ``2**256``. Assert that ``k != 0`` starting from version 0.5.0.
|
||||
|
||||
``mulmod(uint x, uint y, uint k) returns (uint)``:
|
||||
``mulmod(uint x, uint y, uint k) returns (uint)``
|
||||
compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256``. Assert that ``k != 0`` starting from version 0.5.0.
|
||||
|
||||
``keccak256(bytes memory) returns (bytes32)``:
|
||||
``keccak256(bytes memory) returns (bytes32)``
|
||||
compute the Keccak-256 hash of the input
|
||||
|
||||
.. note::
|
||||
|
||||
There used to be an alias for ``keccak256`` called ``sha3``, which was removed in version 0.5.0.
|
||||
|
||||
``sha256(bytes memory) returns (bytes32)``:
|
||||
``sha256(bytes memory) returns (bytes32)``
|
||||
compute the SHA-256 hash of the input
|
||||
|
||||
``ripemd160(bytes memory) returns (bytes20)``:
|
||||
``ripemd160(bytes memory) returns (bytes20)``
|
||||
compute RIPEMD-160 hash of the input
|
||||
|
||||
``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``:
|
||||
``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``
|
||||
recover the address associated with the public key from elliptic curve signature or return zero on error.
|
||||
The function parameters correspond to ECDSA values of the signature:
|
||||
|
||||
``r`` = first 32 bytes of signature
|
||||
``s`` = second 32 bytes of signature
|
||||
``v`` = final 1 byte of signature
|
||||
* ``r`` = first 32 bytes of signature
|
||||
* ``s`` = second 32 bytes of signature
|
||||
* ``v`` = final 1 byte of signature
|
||||
|
||||
``ecrecover`` returns an ``address``, and not an ``address payable``. See :ref:`address payable<address>` for
|
||||
conversion, in case you need to transfer funds to the recovered address.
|
||||
@ -209,17 +213,22 @@ Mathematical and Cryptographic Functions
|
||||
Members of Address Types
|
||||
------------------------
|
||||
|
||||
``<address>.balance`` (``uint256``):
|
||||
``<address>.balance`` (``uint256``)
|
||||
balance of the :ref:`address` in Wei
|
||||
``<address payable>.transfer(uint256 amount)``:
|
||||
|
||||
``<address payable>.transfer(uint256 amount)``
|
||||
send given amount of Wei to :ref:`address`, reverts on failure, forwards 2300 gas stipend, not adjustable
|
||||
``<address payable>.send(uint256 amount) returns (bool)``:
|
||||
|
||||
``<address payable>.send(uint256 amount) returns (bool)``
|
||||
send given amount of Wei to :ref:`address`, returns ``false`` on failure, forwards 2300 gas stipend, not adjustable
|
||||
``<address>.call(bytes memory) returns (bool, bytes memory)``:
|
||||
|
||||
``<address>.call(bytes memory) returns (bool, bytes memory)``
|
||||
issue low-level ``CALL`` with the given payload, returns success condition and return data, forwards all available gas, adjustable
|
||||
``<address>.delegatecall(bytes memory) returns (bool, bytes memory)``:
|
||||
|
||||
``<address>.delegatecall(bytes memory) returns (bool, bytes memory)``
|
||||
issue low-level ``DELEGATECALL`` with the given payload, returns success condition and return data, forwards all available gas, adjustable
|
||||
``<address>.staticcall(bytes memory) returns (bool, bytes memory)``:
|
||||
|
||||
``<address>.staticcall(bytes memory) returns (bool, bytes memory)``
|
||||
issue low-level ``STATICCALL`` with the given payload, returns success condition and return data, forwards all available gas, adjustable
|
||||
|
||||
For more information, see the section on :ref:`address`.
|
||||
@ -258,10 +267,10 @@ For more information, see the section on :ref:`address`.
|
||||
Contract Related
|
||||
----------------
|
||||
|
||||
``this`` (current contract's type):
|
||||
``this`` (current contract's type)
|
||||
the current contract, explicitly convertible to :ref:`address`
|
||||
|
||||
``selfdestruct(address payable recipient)``:
|
||||
``selfdestruct(address payable recipient)``
|
||||
Destroy the current contract, sending its funds to the given :ref:`address`
|
||||
and end execution.
|
||||
Note that ``selfdestruct`` has some peculiarities inherited from the EVM:
|
||||
@ -290,10 +299,10 @@ type ``X``. Currently, there is limited support for this feature, but
|
||||
it might be expanded in the future. The following properties are
|
||||
available for a contract type ``C``:
|
||||
|
||||
``type(C).name``:
|
||||
``type(C).name``
|
||||
The name of the contract.
|
||||
|
||||
``type(C).creationCode``:
|
||||
``type(C).creationCode``
|
||||
Memory byte array that contains the creation bytecode of the contract.
|
||||
This can be used in inline assembly to build custom creation routines,
|
||||
especially by using the ``create2`` opcode.
|
||||
@ -301,7 +310,7 @@ available for a contract type ``C``:
|
||||
derived contract. It causes the bytecode to be included in the bytecode
|
||||
of the call site and thus circular references like that are not possible.
|
||||
|
||||
``type(C).runtimeCode``:
|
||||
``type(C).runtimeCode``
|
||||
Memory byte array that contains the runtime bytecode of the contract.
|
||||
This is the code that is usually deployed by the constructor of ``C``.
|
||||
If ``C`` has a constructor that uses inline assembly, this might be
|
||||
|
||||
@ -106,7 +106,8 @@ Target options
|
||||
Below is a list of target EVM versions and the compiler-relevant changes introduced
|
||||
at each version. Backward compatibility is not guaranteed between each version.
|
||||
|
||||
- ``homestead`` (oldest version)
|
||||
- ``homestead``
|
||||
- (oldest version)
|
||||
- ``tangerineWhistle``
|
||||
- Gas cost for access to other accounts increased, relevant for gas estimation and the optimizer.
|
||||
- All gas sent by default for external calls, previously a certain amount had to be retained.
|
||||
@ -692,7 +693,7 @@ Review changes
|
||||
|
||||
The command above applies all changes as shown below. Please review them carefully.
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: solidity
|
||||
|
||||
pragma solidity >=0.6.0 <0.7.0;
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user