English documentation updates up to v0.8.24-125-gedc494de1 (2024-03-06)

docs/bugs.rst

@@ -7,7 +7,7 @@ List of Known Bugs
 ##################
 
 Below, you can find a JSON-formatted list of some of the known security-relevant bugs in the
-Solidity compiler. The file itself is hosted in the `Github repository
+Solidity compiler. The file itself is hosted in the `GitHub repository
 <https://github.com/ethereum/solidity/blob/develop/docs/bugs.json>`_.
 The list stretches back as far as version 0.3.0, bugs known to be present only
 in versions preceding that are not listed.

docs/cheatsheet.rst

@@ -159,7 +159,7 @@ Modifiers
 - ``pure`` for functions: Disallows modification or access of state.
 - ``view`` for functions: Disallows modification of state.
 - ``payable`` for functions: Allows them to receive Ether together with a call.
-- ``constant`` for state variables: Disallows assignment (except initialisation), does not occupy storage slot.
+- ``constant`` for state variables: Disallows assignment (except initialization), does not occupy storage slot.
 - ``immutable`` for state variables: Allows assignment at construction time and is constant when deployed. Is stored in code.
 - ``anonymous`` for events: Does not store event signature as topic.
 - ``indexed`` for event parameters: Stores the parameter as topic.

docs/contracts/inheritance.rst

@@ -398,7 +398,7 @@ Constructors
 
 A constructor is an optional function declared with the ``constructor`` keyword
 which is executed upon contract creation, and where you can run contract
-initialisation code.
+initialization code.
 
 Before the constructor code is executed, state variables are initialised to
 their specified value if you initialise them inline, or their :ref:`default value<default-value>` if you do not.

docs/contributing.rst

@@ -128,7 +128,7 @@ for the ``evmone`` shared object can be specified via the ``ETH_EVMONE`` environ
 If you do not have it installed, you can skip these tests by passing the ``--no-semantic-tests``
 flag to ``scripts/soltest.sh``.
 
-The ``evmone`` library should both end with the file name
+The ``evmone`` library should end with the file name
 extension ``.so`` on Linux, ``.dll`` on Windows systems and ``.dylib`` on macOS.
 
 For running SMT tests, the ``libz3`` library must be installed and locatable
@@ -552,7 +552,7 @@ topics, issues or feature implementations are debated in detail. The invitation
 
 We are also sharing feedback surveys and other content that is relevant to language design in the forum.
 
-If you want to know where the team is standing in terms or implementing new features, you can follow the implementation status in the `Solidity Github project <https://github.com/ethereum/solidity/projects/43>`_.
+If you want to know where the team is standing in terms or implementing new features, you can follow the implementation status in the `Solidity GitHub project <https://github.com/ethereum/solidity/projects/43>`_.
 Issues in the design backlog need further specification and will either be discussed in a language design call or in a regular team call. You can
 see the upcoming changes for the next breaking release by changing from the default branch (`develop`) to the `breaking branch <https://github.com/ethereum/solidity/tree/breaking>`_.
 

docs/installing-solidity.rst

@@ -83,14 +83,20 @@ and runs it in a new container, passing the ``--help`` argument.
 
     docker run ethereum/solc:stable --help
 
-For example, You can specify release build versions in the tag for the 0.5.4 release.
+You can specify release build versions in the tag. For example:
 
 .. code-block:: bash
 
-    docker run ethereum/solc:0.5.4 --help
+    docker run ethereum/solc:stable --help
+
+Note
+
+Specific compiler versions are supported as the Docker image tag such as `ethereum/solc:0.8.23`. We will be passing the
+`stable` tag here instead of specific version tag to ensure that users get the latest version by default and avoid the issue of
+an out-of-date version.
 
 To use the Docker image to compile Solidity files on the host machine, mount a
-local folder for input and output, and specify the contract to compile. For example.
+local folder for input and output, and specify the contract to compile. For example:
 
 .. code-block:: bash
 
@@ -183,7 +189,7 @@ If you need a specific version of Solidity you can install a
 Homebrew formula directly from Github.
 
 View
-`solidity.rb commits on Github <https://github.com/ethereum/homebrew-ethereum/commits/master/solidity.rb>`_.
+`solidity.rb commits on GitHub <https://github.com/ethereum/homebrew-ethereum/commits/master/solidity.rb>`_.
 
 Copy the commit hash of the version you want and check it out on your machine.
 
@@ -224,8 +230,8 @@ out-of-the-box but it is also meant to be friendly to third-party tools:
   (via git, HTTPS, IPFS or just have it cached locally) and verify hashes of the binaries
   after downloading them, you do not have to use HTTPS for the binaries themselves.
 
-The same binaries are in most cases available on the `Solidity release page on Github`_. The
-difference is that we do not generally update old releases on the Github release page. This means
+The same binaries are in most cases available on the `Solidity release page on GitHub`_. The
+difference is that we do not generally update old releases on the GitHub release page. This means
 that we do not rename them if the naming convention changes and we do not add builds for platforms
 that were not supported at the time of release. This only happens in ``solc-bin``.
 
@@ -301,7 +307,7 @@ This means that:
 .. _IPFS: https://ipfs.io
 .. _Swarm: https://swarm-gateways.net/bzz:/swarm.eth
 .. _solc-bin: https://github.com/ethereum/solc-bin/
-.. _Solidity release page on github: https://github.com/ethereum/solidity/releases
+.. _Solidity release page on GitHub: https://github.com/ethereum/solidity/releases
 .. _sha3sum: https://github.com/maandree/sha3sum
 .. _keccak256() function from ethereumjs-util: https://github.com/ethereumjs/ethereumjs-util/blob/master/docs/modules/_hash_.md#const-keccak256
 .. _WebAssembly builds: https://emscripten.org/docs/compiling/WebAssembly.html
@@ -461,11 +467,11 @@ you should fork Solidity and add your personal fork as a second remote:
     This method will result in a pre-release build leading to e.g. a flag
     being set in each bytecode produced by such a compiler.
     If you want to re-build a released Solidity compiler, then
-    please use the source tarball on the github release page:
+    please use the source tarball on the GitHub release page:
 
     https://github.com/ethereum/solidity/releases/download/v0.X.Y/solidity_0.X.Y.tar.gz
 
-    (not the "Source code" provided by github).
+    (not the "Source code" provided by GitHub).
 
 Command-Line Build
 ------------------

docs/internals/optimizer.rst

@@ -298,7 +298,7 @@ The following transformation steps are the main components:
 - SSA Transform
 - Common Subexpression Eliminator
 - Expression Simplifier
-- Redundant Assign Eliminator
+- Unused Assign Eliminator
 - Full Inliner
 
 .. _optimizer-steps:
@@ -335,11 +335,11 @@ Abbreviation Full name
 ``T``        :ref:`literal-rematerialiser`
 ``L``        :ref:`load-resolver`
 ``M``        :ref:`loop-invariant-code-motion`
-``r``        :ref:`redundant-assign-eliminator`
 ``m``        :ref:`rematerialiser`
 ``V``        :ref:`SSA-reverser`
 ``a``        :ref:`SSA-transform`
 ``t``        :ref:`structural-simplifier`
+``r``        :ref:`unused-assign-eliminator`
 ``p``        :ref:`unused-function-parameter-pruner`
 ``S``        :ref:`unused-store-eliminator`
 ``u``        :ref:`unused-pruner`
@@ -482,7 +482,7 @@ is transformed to
     }
 
 This eases the rest of the optimization process because we can ignore
-the complicated scoping rules of the for loop initialisation block.
+the complicated scoping rules of the for loop initialization block.
 
 .. _var-decl-initializer:
 
@@ -652,18 +652,18 @@ the block, a new SSA variable will be created at the location where control flow
 this includes the beginning of loop post/body block and the location right after
 If/Switch/ForLoop/Block statement.
 
-After this stage, the Redundant Assign Eliminator is recommended to remove the unnecessary
+After this stage, the Unused Assign Eliminator is recommended to remove the unnecessary
 intermediate assignments.
 
 This stage provides best results if the Expression Splitter and the Common Subexpression Eliminator
 are run right before it, because then it does not generate excessive amounts of variables.
 On the other hand, the Common Subexpression Eliminator could be more efficient if run after the
 SSA transform.
 
-.. _redundant-assign-eliminator:
+.. _unused-assign-eliminator:
 
-RedundantAssignEliminator
-^^^^^^^^^^^^^^^^^^^^^^^^^
+UnusedAssignEliminator
+^^^^^^^^^^^^^^^^^^^^^^
 
 The SSA transform always generates an assignment of the form ``a := a_i``, even though
 these might be unnecessary in many cases, like the following example:
@@ -691,7 +691,7 @@ The SSA transform converts this snippet to the following:
         sstore(a_3, 1)
     }
 
-The Redundant Assign Eliminator removes all the three assignments to ``a``, because
+The Unused Assign Eliminator removes all the three assignments to ``a``, because
 the value of ``a`` is not used and thus turn this
 snippet into strict SSA form:
 
@@ -704,7 +704,7 @@ snippet into strict SSA form:
         sstore(a_3, 1)
     }
 
-Of course the intricate parts of determining whether an assignment is redundant or not
+Of course the intricate parts of determining whether an assignment is unused or not
 are connected to joining control flow.
 
 The component works as follows in detail:
@@ -829,7 +829,7 @@ current value if the value is an identifier.
 The combination of the two rules above allow to compute a local value
 numbering, which means that if two variables have the same
 value, one of them will always be unused. The Unused Pruner or the
-Redundant Assign Eliminator will then be able to fully eliminate such
+Unused Assign Eliminator will then be able to fully eliminate such
 variables.
 
 This step is especially efficient if the expression splitter is run
@@ -1217,7 +1217,7 @@ The FullInliner replaces certain calls of certain functions
 by the function's body. This is not very helpful in most cases, because
 it just increases the code size but does not have a benefit. Furthermore,
 code is usually very expensive and we would often rather have shorter
-code than more efficient code. In same cases, though, inlining a function
+code than more efficient code. In some cases, though, inlining a function
 can have positive effects on subsequent optimizer steps. This is the case
 if one of the function arguments is a constant, for example.
 

docs/introduction-to-smart-contracts.rst

@@ -156,7 +156,7 @@ creates a public state variable, but it is a more complex datatype.
 The :ref:`mapping <mapping-types>` type maps addresses to :ref:`unsigned integers <integers>`.
 
 Mappings can be seen as `hash tables <https://en.wikipedia.org/wiki/Hash_table>`_ which are
-virtually initialised such that every possible key exists from the start and is mapped to a
+virtually initialized such that every possible key exists from the start and is mapped to a
 value whose byte-representation is all zeros. However, it is neither possible to obtain a list of all keys of
 a mapping, nor a list of all values. Record what you
 added to the mapping, or use it in a context where this is not needed. Or
@@ -304,7 +304,7 @@ These blocks form a linear sequence in time, and that is where the word "blockch
 Blocks are added to the chain at regular intervals, although these intervals may be subject to change in the future.
 For the most up-to-date information, it is recommended to monitor the network, for example, on `Etherscan <https://etherscan.io/chart/blocktime>`_.
 
-As part of the "order selection mechanism" (which is called "mining") it may happen that
+As part of the "order selection mechanism", which is called `attestation <https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/attestations/>`_, it may happen that
 blocks are reverted from time to time, but only at the "tip" of the chain. The more
 blocks are added on top of a particular block, the less likely this block will be reverted. So it might be that your transactions
 are reverted and even removed from the blockchain, but the longer you wait, the less

docs/natspec-format.rst

@@ -115,10 +115,10 @@ in the same way as if it were tagged with ``@notice``.
 =============== ====================================================================================== =============================
 Tag                                                                                                    Context
 =============== ====================================================================================== =============================
-``@title``      A title that should describe the contract/interface                                    contract, library, interface
-``@author``     The name of the author                                                                 contract, library, interface
-``@notice``     Explain to an end user what this does                                                  contract, library, interface, function, public state variable, event
-``@dev``        Explain to a developer any extra details                                               contract, library, interface, function, state variable, event
+``@title``      A title that should describe the contract/interface                                    contract, library, interface, struct, enum
+``@author``     The name of the author                                                                 contract, library, interface, struct, enum
+``@notice``     Explain to an end user what this does                                                  contract, library, interface, function, public state variable, event, struct, enum
+``@dev``        Explain to a developer any extra details                                               contract, library, interface, function, state variable, event, struct, enum
 ``@param``      Documents a parameter just like in Doxygen (must be followed by parameter name)        function, event
 ``@return``     Documents the return variables of a contract's function                                function, public state variable
 ``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, public state variable