From d59706e5f5da3e68012a810ec5f31a44eb13f712 Mon Sep 17 00:00:00 2001 From: iamdefinitelyahuman Date: Mon, 20 Apr 2020 20:24:31 +0400 Subject: [PATCH] docs: fix formatting errors and style inconsistencies --- docs/contracts/functions.rst | 10 ++-- docs/contracts/visibility-and-getters.rst | 8 +-- docs/examples/micropayment.rst | 2 +- docs/installing-solidity.rst | 10 ++-- docs/introduction-to-smart-contracts.rst | 6 +-- docs/natspec-format.rst | 4 +- docs/style-guide.rst | 14 +++--- docs/types.rst | 4 +- docs/types/value-types.rst | 2 +- docs/units-and-global-variables.rst | 59 +++++++++++++---------- docs/using-the-compiler.rst | 5 +- 11 files changed, 68 insertions(+), 56 deletions(-) diff --git a/docs/contracts/functions.rst b/docs/contracts/functions.rst index 8b9e7df64..7a0ec2e08 100644 --- a/docs/contracts/functions.rst +++ b/docs/contracts/functions.rst @@ -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 `. 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 ` 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 diff --git a/docs/contracts/visibility-and-getters.rst b/docs/contracts/visibility-and-getters.rst index 5ef105784..04af8a26f 100644 --- a/docs/contracts/visibility-and-getters.rst +++ b/docs/contracts/visibility-and-getters.rst @@ -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. diff --git a/docs/examples/micropayment.rst b/docs/examples/micropayment.rst index b4f1f6c6b..ab69fd296 100644 --- a/docs/examples/micropayment.rst +++ b/docs/examples/micropayment.rst @@ -454,7 +454,7 @@ The recipient should verify each message using the following process: We'll use the `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: :: diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst index d02651a2e..27a20b3bc 100644 --- a/docs/installing-solidity.rst +++ b/docs/installing-solidity.rst @@ -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 `_. 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 ====== diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst index a5f056493..e3e38b92c 100644 --- a/docs/introduction-to-smart-contracts.rst +++ b/docs/introduction-to-smart-contracts.rst @@ -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``, diff --git a/docs/natspec-format.rst b/docs/natspec-format.rst index ae429580a..1776925ee 100644 --- a/docs/natspec-format.rst +++ b/docs/natspec-format.rst @@ -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 diff --git a/docs/style-guide.rst b/docs/style-guide.rst index c637c8379..c2990824d 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -24,8 +24,11 @@ solidity code. The goal of this guide is *consistency*. A quote from python's `pep8 `_ 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 `_ 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 `_ with the comments added looks like the one below:: diff --git a/docs/types.rst b/docs/types.rst index b9c06f6c8..d929a274f 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -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` dependent on its type. To handle any unexpected values, you should use the :ref:`revert function` 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 \ No newline at end of file +.. include:: types/conversion.rst diff --git a/docs/types/value-types.rst b/docs/types/value-types.rst index 80b9d548c..0301a8ad5 100644 --- a/docs/types/value-types.rst +++ b/docs/types/value-types.rst @@ -332,7 +332,7 @@ the :ref:`address type
`. 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. diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 6c625e997..75ed7546f 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -140,15 +140,19 @@ Error Handling See the dedicated section on :ref:`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
` 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 ------------------------ -``
.balance`` (``uint256``): +``
.balance`` (``uint256``) balance of the :ref:`address` in Wei -``
.transfer(uint256 amount)``: + +``
.transfer(uint256 amount)`` send given amount of Wei to :ref:`address`, reverts on failure, forwards 2300 gas stipend, not adjustable -``
.send(uint256 amount) returns (bool)``: + +``
.send(uint256 amount) returns (bool)`` send given amount of Wei to :ref:`address`, returns ``false`` on failure, forwards 2300 gas stipend, not adjustable -``
.call(bytes memory) returns (bool, bytes memory)``: + +``
.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 -``
.delegatecall(bytes memory) returns (bool, bytes memory)``: + +``
.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 -``
.staticcall(bytes memory) returns (bool, bytes memory)``: + +``
.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 diff --git a/docs/using-the-compiler.rst b/docs/using-the-compiler.rst index 02218592e..ea573ed70 100644 --- a/docs/using-the-compiler.rst +++ b/docs/using-the-compiler.rst @@ -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;