Merge remote-tracking branch 'origin/develop' into breaking

docs/Solidity.g4

@@ -359,10 +359,10 @@ subAssembly
   : 'assembly' identifier assemblyBlock ;
 
 numberLiteral
-  : (DecimalNumber | HexNumber) NumberUnit? ;
+  : (DecimalNumber | HexNumber) (NumberUnit | Gwei)?;
 
 identifier
-  : ('from' | 'calldata' | 'address' | Identifier) ;
+  : (Gwei | 'from' | 'calldata' | 'address' | Identifier) ;
 
 BooleanLiteral
   : 'true' | 'false' ;
@@ -385,6 +385,8 @@ NumberUnit
   : 'wei' | 'szabo' | 'finney' | 'ether'
   | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'years' ;
 
+Gwei: 'gwei' ;
+
 HexLiteralFragment
   : 'hex' (('"' HexDigits? '"') | ('\'' HexDigits? '\'')) ;
 

docs/natspec-format.rst

@@ -42,10 +42,6 @@ The following example shows a contract and a function using all available tags.
 
 .. note::
 
-  NatSpec currently does NOT apply to public state variables (see
-  `solidity#3418 <https://github.com/ethereum/solidity/issues/3418>`__),
-  even if they are declared public and therefore do affect the ABI.
-
   The Solidity compiler only interprets tags if they are external or
   public. You are welcome to use similar comments for your internal and
   private functions, but those will not be parsed.
@@ -60,7 +56,6 @@ The following example shows a contract and a function using all available tags.
     /// @notice You can use this contract for only the most basic simulation
     /// @dev All function calls are currently implemented without side effects
     contract Tree {
-        /// @author Mary A. Botanist
         /// @notice Calculate tree age in years, rounded up, for live trees
         /// @dev The Alexandr N. Tetearing algorithm could increase precision
         /// @param rings The number of rings from dendrochronological sample
@@ -84,10 +79,10 @@ in the same way as if it were tagged with ``@notice``.
 Tag                                                                                         Context
 =========== =============================================================================== =============================
 ``@title``  A title that should describe the contract/interface                             contract, interface
-``@author`` The name of the author                                                          contract, interface, function
-``@notice`` Explain to an end user what this does                                           contract, interface, function, public state variable
-``@dev``    Explain to a developer any extra details                                        contract, interface, function, state variable
-``@param``  Documents a parameter just like in doxygen (must be followed by parameter name) function
+``@author`` The name of the author                                                          contract, interface
+``@notice`` Explain to an end user what this does                                           contract, interface, function, public state variable, event
+``@dev``    Explain to a developer any extra details                                        contract, interface, function, state variable, event
+``@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
 =========== =============================================================================== =============================
 
@@ -127,9 +122,11 @@ documentation and you may read more at
 Inheritance Notes
 -----------------
 
-Currently it is undefined whether a contract with a function having no
-NatSpec will inherit the NatSpec of a parent contract/interface for that
-same function.
+Functions without NatSpec will automatically inherit the documentation of their
+base function. Exceptions to this are:
+
+ * When the parameter names are different.
+ * When there is more than one base function.
 
 .. _header-output:
 
@@ -193,7 +190,6 @@ file should also be produced and should look like this:
       {
         "age(uint256)" :
         {
-          "author" : "Mary A. Botanist",
           "details" : "The Alexandr N. Tetearing algorithm could increase precision",
           "params" :
           {

docs/units-and-global-variables.rst

@@ -7,11 +7,12 @@ Units and Globally Available Variables
 Ether Units
 ===========
 
-A literal number can take a suffix of ``wei``, ``finney``, ``szabo`` or ``ether`` to specify a subdenomination of Ether, where Ether numbers without a postfix are assumed to be Wei.
+A literal number can take a suffix of ``wei``, ``gwei``, ``finney``, ``szabo`` or ``ether`` to specify a subdenomination of Ether, where Ether numbers without a postfix are assumed to be Wei.
 
 ::
 
     assert(1 wei == 1);
+    assert(1 gwei == 1e9);
     assert(1 szabo == 1e12);
     assert(1 finney == 1e15);
     assert(1 ether == 1e18);

docs/yul.rst

@@ -180,7 +180,11 @@ appropriate ``PUSHi`` instruction. In the following example,
 ``3`` and ``2`` are added resulting in 5 and then the
 bitwise ``and`` with the string "abc" is computed.
 The final value is assigned to a local variable called ``x``.
+
 Strings are stored left-aligned and cannot be longer than 32 bytes.
+The limit does not apply to string literals passed to builtin functions that require
+literal arguments (e.g. ``setimmutable`` or ``loadimmutable``). Those strings never end up in the
+generated bytecode.
 
 .. code-block:: yul
 
@@ -923,6 +927,30 @@ will store ``value`` at all points in memory that contain a call to
 ``loadimmutable("name")``.
 
 
+linkersymbol
+^^^^^^^^^^^^
+
+The function ``linkersymbol("fq_library_name")`` is a placeholder for an address literal to be
+substituted by the linker. Its first and only argument must be a string literal and represents the
+fully qualified library name used with the ``--libraries`` option.
+
+For example this code
+
+.. code-block:: yul
+
+    let a := linkersymbol("file.sol:Math")
+
+is equivalent to
+
+.. code-block:: yul
+
+    let a := 0x1234567890123456789012345678901234567890
+
+when the linker is invoked with ``--libraries "file.sol:Math:0x1234567890123456789012345678901234567890``
+option.
+
+See :ref:`Using the Commandline Compiler <commandline-compiler>` for details about the Solidity linker.
+
 
 .. _yul-object: