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

Changelog.md

@@ -43,9 +43,12 @@ Compiler Features:
  * Code Generator: Evaluate ``keccak256`` of string literals at compile-time.
  * Peephole Optimizer: Remove unnecessary masking of tags.
  * Yul EVM Code Transform: Free stack slots directly after visiting the right-hand-side of variable declarations instead of at the end of the statement only.
+ * NatSpec: Implement tag ``@inheritdoc`` to copy documentation from a specific contract.
 
 Bugfixes:
  * SMTChecker: Fix internal error when using bitwise operators on fixed bytes type.
+ * SMTChecker: Fix internal error when using compound bitwise operator assignments on array indices inside branches.
+ * SMTChecker: Fix error in events with indices of type static array.
  * Type Checker: Fix overload resolution in combination with ``{value: ...}``.
  * Type Checker: Fix internal compiler error related to oversized types.
  * Code Generator: Avoid double cleanup when copying to memory.

docs/natspec-format.rst

@@ -49,7 +49,7 @@ The following example shows a contract and a function using all available tags.
 .. code:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >=0.5.0 <0.8.0;
+    pragma solidity >0.6.10 <0.8.0;
 
     /// @title A simulator for trees
     /// @author Larry A. Gardner
@@ -60,9 +60,33 @@ The following example shows a contract and a function using all available tags.
         /// @dev The Alexandr N. Tetearing algorithm could increase precision
         /// @param rings The number of rings from dendrochronological sample
         /// @return age in years, rounded up for partial years
-        function age(uint256 rings) external pure returns (uint256) {
+        function age(uint256 rings) external virtual pure returns (uint256) {
             return rings + 1;
         }
+
+        /// @notice Returns the amount of leaves the tree has.
+        /// @dev Returns only a fixed number.
+        function leaves() external virtual pure returns(uint256) {
+            return 2;
+        }
+    }
+
+    contract Plant {
+        function leaves() external virtual pure returns(uint256) {
+            return 3;
+        }
+    }
+
+    contract KumquatTree is Tree, Plant {
+        function age(uint256 rings) external override pure returns (uint256) {
+            return rings + 2;
+        }
+
+        /// Return the amount of leaves that this specific kind of tree has
+        /// @inheritdoc Tree
+        function leaves() external override(Tree, Plant) pure returns(uint256) {
+            return 3;
+        }
     }
 
 .. _header-tags:
@@ -75,16 +99,17 @@ 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``.
 
-=========== =============================================================================== =============================
-Tag                                                                                         Context
-=========== =============================================================================== =============================
-``@title``  A title that should describe the contract/interface                             contract, interface
-``@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
-=========== =============================================================================== =============================
+=============== ====================================================================================== =============================
+Tag                                                                                                    Context
+=============== ====================================================================================== =============================
+``@title``      A title that should describe the contract/interface                                    contract, interface
+``@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
+``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, public state variable
+=============== ====================================================================================== =============================
 
 If your function returns multiple values, like ``(int quotient, int remainder)``
 then use multiple ``@return`` statements in the same format as the
@@ -127,6 +152,7 @@ base function. Exceptions to this are:
 
  * When the parameter names are different.
  * When there is more than one base function.
+ * When there is an explicit ``@inheritdoc`` tag which specifies which contract should be used to inherit.
 
 .. _header-output:
 

libevmasm/Assembly.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file Assembly.cpp
  * @author Gav Wood <i@gavwood.com>
  * @date 2014
@@ -521,6 +522,7 @@ map<u256, u256> Assembly::optimiseInternal(
 
 LinkerObject const& Assembly::assemble() const
 {
+	assertThrow(!m_invalid, AssemblyException, "Attempted to assemble invalid Assembly object.");
 	// Return the already assembled object, if present.
 	if (!m_assembledObject.bytecode.empty())
 		return m_assembledObject;

libevmasm/Assembly.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 
@@ -142,6 +143,9 @@ public:
 		std::map<std::string, unsigned> const& _sourceIndices = std::map<std::string, unsigned>()
 	) const;
 
+	/// Mark this assembly as invalid. Calling ``assemble`` on it will throw.
+	void markAsInvalid() { m_invalid = true; }
+
 protected:
 	/// Does the same operations as @a optimise, but should only be applied to a sub and
 	/// returns the replaced tags. Also takes an argument containing the tags of this assembly
@@ -161,6 +165,7 @@ private:
 	);
 	static std::string toStringInHex(u256 _value);
 
+	bool m_invalid = false;
 protected:
 	/// 0 is reserved for exception
 	unsigned m_usedTags = 1;

libevmasm/AssemblyItem.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libevmasm/AssemblyItem.h>
 

libevmasm/AssemblyItem.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file AssemblyItem.h
  * @author Gav Wood <i@gavwood.com>
  * @date 2014

libevmasm/BlockDeduplicator.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file BlockDeduplicator.cpp
  * @author Christian <c@ethdev.com>

libevmasm/BlockDeduplicator.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file BlockDeduplicator.h
  * @author Christian <c@ethdev.com>

libevmasm/CommonSubexpressionEliminator.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file CommonSubexpressionEliminator.cpp
  * @author Christian <c@ethdev.com>

libevmasm/CommonSubexpressionEliminator.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file CommonSubexpressionEliminator.h
  * @author Christian <c@ethdev.com>

libevmasm/ConstantOptimiser.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file ConstantOptimiser.cpp
  * @author Christian <c@ethdev.com>
  * @date 2015

libevmasm/ConstantOptimiser.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file ConstantOptimiser.cpp
  * @author Christian <c@ethdev.com>
  * @date 2015

libevmasm/ControlFlowGraph.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file ControlFlowGraph.cpp
  * @author Christian <c@ethdev.com>

libevmasm/ControlFlowGraph.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file ControlFlowGraph.h
  * @author Christian <c@ethdev.com>

libevmasm/Exceptions.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file Exceptions.h
  * @author Christian <c@ethdev.com>
  * @date 2014

libevmasm/ExpressionClasses.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file ExpressionClasses.cpp
  * @author Christian <c@ethdev.com>

libevmasm/ExpressionClasses.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file ExpressionClasses.h
  * @author Christian <c@ethdev.com>

libevmasm/GasMeter.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libevmasm/GasMeter.h>
 

libevmasm/GasMeter.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file GasMeter.cpp
  * @author Christian <c@ethdev.com>
  * @date 2015

libevmasm/Instruction.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file Instruction.cpp
  * @author Gav Wood <i@gavwood.com>
  * @date 2014

libevmasm/Instruction.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file Instruction.h
  * @author Gav Wood <i@gavwood.com>
  * @date 2014

libevmasm/JumpdestRemover.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Alex Beregszaszi
  * Removes unused JUMPDESTs.

libevmasm/JumpdestRemover.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Alex Beregszaszi
  * Removes unused JUMPDESTs.

libevmasm/KnownState.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file KnownState.cpp
  * @author Christian <c@ethdev.com>

libevmasm/KnownState.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file KnownState.h
  * @author Christian <c@ethdev.com>

libevmasm/LinkerObject.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file LinkerObject.cpp
  * @author Christian R <c@ethdev.com>
  * @date 2015

libevmasm/LinkerObject.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file Assembly.h
  * @author Gav Wood <i@gavwood.com>
  * @date 2014

libevmasm/PathGasMeter.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file PathGasMeter.cpp
  * @author Christian <c@ethdev.com>
  * @date 2015

libevmasm/PathGasMeter.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file PathGasMeter.cpp
  * @author Christian <c@ethdev.com>
  * @date 2015

libevmasm/PeepholeOptimiser.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file PeepholeOptimiser.cpp
  * Performs local optimising code changes to assembly.

libevmasm/PeepholeOptimiser.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file PeepholeOptimiser.h
  * Performs local optimising code changes to assembly.

libevmasm/RuleList.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @date 2018
  * Templatized list of simplification rules.

libevmasm/SemanticInformation.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file SemanticInformation.cpp
  * @author Christian <c@ethdev.com>

libevmasm/SemanticInformation.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file SemanticInformation.h
  * @author Christian <c@ethdev.com>

libevmasm/SimplificationRule.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * Expression simplification pattern.
  */

libevmasm/SimplificationRules.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file ExpressionClasses.cpp
  * @author Christian <c@ethdev.com>

libevmasm/SimplificationRules.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @file SimplificationRules
  * @author Christian <chris@ethereum.org>

liblangutil/EVMVersion.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * EVM versioning.
  */

liblangutil/EVMVersion.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * EVM versioning.
  */

liblangutil/ErrorReporter.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Rhett <roadriverrail@gmail.com>
  * @date 2017

liblangutil/ErrorReporter.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Rhett <roadriverrail@gmail.com>
  * @date 2017

liblangutil/Exceptions.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Liana <liana@ethdev.com>
  * @date 2015

liblangutil/Exceptions.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014

liblangutil/ParserBase.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2016

liblangutil/ParserBase.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2016

liblangutil/SemVerHandler.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <chris@ethereum.org>
  * @date 2016

liblangutil/SemVerHandler.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <chris@ethereum.org>
  * @date 2016

liblangutil/SourceLocation.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <liblangutil/Exceptions.h>
 

liblangutil/SourceLocation.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Lefteris Karapetsas <lefteris@ethdev.com>
  * @date 2015

liblangutil/SourceReferenceExtractor.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 #include <liblangutil/SourceReferenceExtractor.h>
 #include <liblangutil/CharStream.h>
 #include <liblangutil/Exceptions.h>

liblangutil/SourceReferenceExtractor.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 #pragma once
 
 #include <liblangutil/Exceptions.h>

liblangutil/SourceReferenceFormatter.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014

liblangutil/SourceReferenceFormatter.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014

liblangutil/SourceReferenceFormatterHuman.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * Formatting functions for errors referencing positions and locations in the source.
  */

liblangutil/SourceReferenceFormatterHuman.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * Formatting functions for errors referencing positions and locations in the source.
  */

liblangutil/UndefMacros.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /** @file UndefMacros.h
  * @author Lefteris  <lefteris@ethdev.com>
  * @date 2015

libsmtutil/CHCSmtLib2Interface.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsmtutil/CHCSmtLib2Interface.h>
 

libsmtutil/CHCSmtLib2Interface.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 /**
  * Interface for solving Horn systems via smtlib2.

libsmtutil/CHCSolverInterface.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 /**
  * Interface for constrained Horn solvers.

libsmtutil/CVC4Interface.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsmtutil/CVC4Interface.h>
 

libsmtutil/CVC4Interface.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsmtutil/Exceptions.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsmtutil/SMTLib2Interface.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsmtutil/SMTLib2Interface.h>
 

libsmtutil/SMTLib2Interface.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsmtutil/SMTPortfolio.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsmtutil/SMTPortfolio.h>
 

libsmtutil/SMTPortfolio.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsmtutil/SolverInterface.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsmtutil/Sorts.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 
 #include <libsmtutil/Sorts.h>

libsmtutil/Sorts.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsmtutil/Z3CHCInterface.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsmtutil/Z3CHCInterface.h>
 

libsmtutil/Z3CHCInterface.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 /**
  * Z3 specific Horn solver interface.

libsmtutil/Z3Interface.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsmtutil/Z3Interface.h>
 

libsmtutil/Z3Interface.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsolc/libsolc.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014

libsolc/libsolc.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014

libsolidity/CMakeLists.txt

@@ -16,6 +16,8 @@ set(sources
 	analysis/DeclarationTypeChecker.h
 	analysis/DocStringAnalyser.cpp
 	analysis/DocStringAnalyser.h
+	analysis/DocStringTagParser.cpp
+	analysis/DocStringTagParser.h
 	analysis/ImmutableValidator.cpp
 	analysis/ImmutableValidator.h
 	analysis/GlobalContext.cpp

libsolidity/analysis/ConstantEvaluator.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2015

libsolidity/analysis/ConstantEvaluator.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2015

libsolidity/analysis/ContractLevelChecker.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * Component that verifies overloads, abstract contracts, function clashes and others
  * checks at contract or function level.

libsolidity/analysis/ContractLevelChecker.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * Component that verifies overloads, abstract contracts, function clashes and others
  * checks at contract or function level.

libsolidity/analysis/ControlFlowAnalyzer.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsolidity/analysis/ControlFlowAnalyzer.h>
 

libsolidity/analysis/ControlFlowAnalyzer.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsolidity/analysis/ControlFlowBuilder.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsolidity/analysis/ControlFlowBuilder.h>
 #include <libyul/AsmData.h>

libsolidity/analysis/ControlFlowBuilder.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsolidity/analysis/ControlFlowGraph.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsolidity/analysis/ControlFlowGraph.h>
 

libsolidity/analysis/ControlFlowGraph.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsolidity/analysis/DeclarationContainer.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014

libsolidity/analysis/DeclarationContainer.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014

libsolidity/analysis/DeclarationTypeChecker.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsolidity/analysis/DeclarationTypeChecker.h>
 

libsolidity/analysis/DeclarationTypeChecker.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsolidity/analysis/DocStringAnalyser.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2015
@@ -52,6 +53,17 @@ void copyMissingTags(StructurallyDocumentedAnnotation& _target, set<CallableDecl
 			_target.docTags.emplace(tag, content);
 }
 
+CallableDeclaration const* findBaseCallable(set<CallableDeclaration const*> const& _baseFunctions, int64_t _contractId)
+{
+	for (CallableDeclaration const* baseFuncCandidate: _baseFunctions)
+		if (baseFuncCandidate->annotation().contract->id() == _contractId)
+			return baseFuncCandidate;
+		else if (auto callable = findBaseCallable(baseFuncCandidate->annotation().baseFunctions, _contractId))
+			return callable;
+
+	return nullptr;
+}
+
 bool parameterNamesEqual(CallableDeclaration const& _a, CallableDeclaration const& _b)
 {
 	return boost::range::equal(_a.parameters(), _b.parameters(), [](auto const& pa, auto const& pb) { return pa->name() == pb->name(); });
@@ -66,37 +78,23 @@ bool DocStringAnalyser::analyseDocStrings(SourceUnit const& _sourceUnit)
 	return errorWatcher.ok();
 }
 
-bool DocStringAnalyser::visit(ContractDefinition const& _contract)
-{
-	static set<string> const validTags = set<string>{"author", "title", "dev", "notice"};
-	parseDocStrings(_contract, _contract.annotation(), validTags, "contracts");
-
-	return true;
-}
-
 bool DocStringAnalyser::visit(FunctionDefinition const& _function)
 {
-	if (_function.isConstructor())
-		handleConstructor(_function, _function, _function.annotation());
-	else
+	if (!_function.isConstructor())
 		handleCallable(_function, _function, _function.annotation());
 	return true;
 }
 
 bool DocStringAnalyser::visit(VariableDeclaration const& _variable)
 {
-	if (_variable.isStateVariable())
-	{
-		static set<string> const validPublicTags = set<string>{"dev", "notice", "return"};
-		static set<string> const validNonPublicTags = set<string>{"dev"};
-		if (_variable.isPublic())
-			parseDocStrings(_variable, _variable.annotation(), validPublicTags, "public state variables");
-		else
-			parseDocStrings(_variable, _variable.annotation(), validNonPublicTags, "non-public state variables");
+	if (!_variable.isStateVariable())
+		return false;
+
+	if (CallableDeclaration const* baseFunction = resolveInheritDoc(_variable.annotation().baseFunctions, _variable, _variable.annotation()))
+		copyMissingTags(_variable.annotation(), {baseFunction});
+	else if (_variable.annotation().docTags.empty())
+		copyMissingTags(_variable.annotation(), _variable.annotation().baseFunctions);
 
-		if (_variable.annotation().docTags.empty())
-			copyMissingTags(_variable.annotation(), _variable.annotation().baseFunctions);
-	}
 	return false;
 }
 
@@ -114,133 +112,41 @@ bool DocStringAnalyser::visit(EventDefinition const& _event)
 	return true;
 }
 
-void DocStringAnalyser::checkParameters(
-	CallableDeclaration const& _callable,
-	StructurallyDocumented const& _node,
-	StructurallyDocumentedAnnotation& _annotation
-)
-{
-	set<string> validParams;
-	for (auto const& p: _callable.parameters())
-		validParams.insert(p->name());
-	if (_callable.returnParameterList())
-		for (auto const& p: _callable.returnParameterList()->parameters())
-			validParams.insert(p->name());
-	auto paramRange = _annotation.docTags.equal_range("param");
-	for (auto i = paramRange.first; i != paramRange.second; ++i)
-		if (!validParams.count(i->second.paramName))
-			m_errorReporter.docstringParsingError(
-				3881_error,
-				_node.documentation()->location(),
-				"Documented parameter \"" +
-				i->second.paramName +
-				"\" not found in the parameter list of the function."
-			);
-
-}
-
-void DocStringAnalyser::handleConstructor(
-	CallableDeclaration const& _callable,
-	StructurallyDocumented const& _node,
-	StructurallyDocumentedAnnotation& _annotation
-)
-{
-	static set<string> const validTags = set<string>{"author", "dev", "notice", "param"};
-	parseDocStrings(_node, _annotation, validTags, "constructor");
-	checkParameters(_callable, _node, _annotation);
-}
-
 void DocStringAnalyser::handleCallable(
 	CallableDeclaration const& _callable,
 	StructurallyDocumented const& _node,
 	StructurallyDocumentedAnnotation& _annotation
 )
 {
-	static set<string> const validTags = set<string>{"author", "dev", "notice", "return", "param"};
-	parseDocStrings(_node, _annotation, validTags, "functions");
-	checkParameters(_callable, _node, _annotation);
-
-	if (
+	if (CallableDeclaration const* baseFunction = resolveInheritDoc(_callable.annotation().baseFunctions, _node, _annotation))
+		copyMissingTags(_annotation, {baseFunction});
+	else if (
 		_annotation.docTags.empty() &&
 		_callable.annotation().baseFunctions.size() == 1 &&
 		parameterNamesEqual(_callable, **_callable.annotation().baseFunctions.begin())
 	)
 		copyMissingTags(_annotation, _callable.annotation().baseFunctions);
-
-	if (_node.documentation() && _annotation.docTags.count("author") > 0)
-		m_errorReporter.warning(
-			9843_error, _node.documentation()->location(),
-			"Documentation tag @author is only allowed on contract definitions. "
-			"It will be disallowed in 0.7.0."
-		);
 }
 
-void DocStringAnalyser::parseDocStrings(
+CallableDeclaration const* DocStringAnalyser::resolveInheritDoc(
+	set<CallableDeclaration const*> const& _baseFuncs,
 	StructurallyDocumented const& _node,
-	StructurallyDocumentedAnnotation& _annotation,
-	set<string> const& _validTags,
-	string const& _nodeName
+	StructurallyDocumentedAnnotation& _annotation
 )
 {
-	DocStringParser parser;
-	if (_node.documentation() && !_node.documentation()->text()->empty())
-	{
-		parser.parse(*_node.documentation()->text(), m_errorReporter);
-		_annotation.docTags = parser.tags();
-	}
+	if (_annotation.inheritdocReference == nullptr)
+		return nullptr;
 
-	size_t returnTagsVisited = 0;
-	for (auto const& docTag: _annotation.docTags)
-	{
-		if (!_validTags.count(docTag.first))
-			m_errorReporter.docstringParsingError(
-				6546_error,
-				_node.documentation()->location(),
-				"Documentation tag @" + docTag.first + " not valid for " + _nodeName + "."
-			);
-		else
-			if (docTag.first == "return")
-			{
-				returnTagsVisited++;
-				if (auto* varDecl = dynamic_cast<VariableDeclaration const*>(&_node))
-				{
-					if (!varDecl->isPublic())
-						m_errorReporter.docstringParsingError(
-							9440_error,
-							_node.documentation()->location(),
-							"Documentation tag \"@" + docTag.first + "\" is only allowed on public state-variables."
-						);
-					if (returnTagsVisited > 1)
-						m_errorReporter.docstringParsingError(
-							5256_error,
-							_node.documentation()->location(),
-							"Documentation tag \"@" + docTag.first + "\" is only allowed once on state-variables."
-						);
-				}
-				else if (auto* function = dynamic_cast<FunctionDefinition const*>(&_node))
-				{
-					string content = docTag.second.content;
-					string firstWord = content.substr(0, content.find_first_of(" \t"));
+	if (auto const callable = findBaseCallable(_baseFuncs, _annotation.inheritdocReference->id()))
+		return callable;
 
-					if (returnTagsVisited > function->returnParameters().size())
-						m_errorReporter.docstringParsingError(
-							2604_error,
-							_node.documentation()->location(),
-							"Documentation tag \"@" + docTag.first + " " + docTag.second.content + "\"" +
-							" exceeds the number of return parameters."
-						);
-					else
-					{
-						auto parameter = function->returnParameters().at(returnTagsVisited - 1);
-						if (!parameter->name().empty() && parameter->name() != firstWord)
-							m_errorReporter.docstringParsingError(
-								5856_error,
-								_node.documentation()->location(),
-								"Documentation tag \"@" + docTag.first + " " + docTag.second.content + "\"" +
-								" does not contain the name of its return parameter."
-							);
-					}
-				}
-			}
-	}
+	m_errorReporter.docstringParsingError(
+		4682_error,
+		_node.documentation()->location(),
+		"Documentation tag @inheritdoc references contract \"" +
+		_annotation.inheritdocReference->name() +
+		"\", but the contract does not contain a function that is overridden by this function."
+	);
+
+	return nullptr;
 }

libsolidity/analysis/DocStringAnalyser.h

@@ -14,12 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
-/**
- * @author Christian <c@ethdev.com>
- * @date 2015
- * Parses and analyses the doc strings.
- * Stores the parsing results in the AST annotations and reports errors.
- */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 
@@ -34,7 +29,7 @@ namespace solidity::frontend
 {
 
 /**
- * Parses and analyses the doc strings.
+ * Analyses and validates the doc strings.
  * Stores the parsing results in the AST annotations and reports errors.
  */
 class DocStringAnalyser: private ASTConstVisitor
@@ -44,20 +39,13 @@ public:
 	bool analyseDocStrings(SourceUnit const& _sourceUnit);
 
 private:
-	bool visit(ContractDefinition const& _contract) override;
 	bool visit(FunctionDefinition const& _function) override;
 	bool visit(VariableDeclaration const& _variable) override;
 	bool visit(ModifierDefinition const& _modifier) override;
 	bool visit(EventDefinition const& _event) override;
 
-	void checkParameters(
-		CallableDeclaration const& _callable,
-		StructurallyDocumented const& _node,
-		StructurallyDocumentedAnnotation& _annotation
-	);
-
-	void handleConstructor(
-		CallableDeclaration const& _callable,
+	CallableDeclaration const* resolveInheritDoc(
+		std::set<CallableDeclaration const*> const& _baseFunctions,
 		StructurallyDocumented const& _node,
 		StructurallyDocumentedAnnotation& _annotation
 	);
@@ -68,19 +56,6 @@ private:
 		StructurallyDocumentedAnnotation& _annotation
 	);
 
-	void handleDeclaration(
-		Declaration const& _declaration,
-		StructurallyDocumented const& _node,
-		StructurallyDocumentedAnnotation& _annotation
-	);
-
-	void parseDocStrings(
-		StructurallyDocumented const& _node,
-		StructurallyDocumentedAnnotation& _annotation,
-		std::set<std::string> const& _validTags,
-		std::string const& _nodeName
-	);
-
 	langutil::ErrorReporter& m_errorReporter;
 };
 

libsolidity/analysis/DocStringTagParser.cpp

@@ -0,0 +1,214 @@
+/*
+	This file is part of solidity.
+
+	solidity is free software: you can redistribute it and/or modify
+	it under the terms of the GNU General Public License as published by
+	the Free Software Foundation, either version 3 of the License, or
+	(at your option) any later version.
+
+	solidity is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU General Public License for more details.
+
+	You should have received a copy of the GNU General Public License
+	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/**
+ * @author Christian <c@ethdev.com>
+ * @date 2015
+ * Parses and analyses the doc strings.
+ * Stores the parsing results in the AST annotations and reports errors.
+ */
+
+#include <libsolidity/analysis/DocStringTagParser.h>
+
+#include <libsolidity/ast/AST.h>
+#include <libsolidity/parsing/DocStringParser.h>
+#include <libsolidity/analysis/NameAndTypeResolver.h>
+#include <liblangutil/ErrorReporter.h>
+
+using namespace std;
+using namespace solidity;
+using namespace solidity::langutil;
+using namespace solidity::frontend;
+
+bool DocStringTagParser::parseDocStrings(SourceUnit const& _sourceUnit)
+{
+	auto errorWatcher = m_errorReporter.errorWatcher();
+	_sourceUnit.accept(*this);
+	return errorWatcher.ok();
+}
+
+bool DocStringTagParser::visit(ContractDefinition const& _contract)
+{
+	static set<string> const validTags = set<string>{"author", "title", "dev", "notice"};
+	parseDocStrings(_contract, _contract.annotation(), validTags, "contracts");
+
+	return true;
+}
+
+bool DocStringTagParser::visit(FunctionDefinition const& _function)
+{
+	if (_function.isConstructor())
+		handleConstructor(_function, _function, _function.annotation());
+	else
+		handleCallable(_function, _function, _function.annotation());
+	return true;
+}
+
+bool DocStringTagParser::visit(VariableDeclaration const& _variable)
+{
+	if (_variable.isStateVariable())
+	{
+		static set<string> const validPublicTags = set<string>{"dev", "notice", "return"};
+		static set<string> const validNonPublicTags = set<string>{"dev"};
+		if (_variable.isPublic())
+			parseDocStrings(_variable, _variable.annotation(), validPublicTags, "public state variables");
+		else
+			parseDocStrings(_variable, _variable.annotation(), validNonPublicTags, "non-public state variables");
+	}
+	return false;
+}
+
+bool DocStringTagParser::visit(ModifierDefinition const& _modifier)
+{
+	handleCallable(_modifier, _modifier, _modifier.annotation());
+
+	return true;
+}
+
+bool DocStringTagParser::visit(EventDefinition const& _event)
+{
+	handleCallable(_event, _event, _event.annotation());
+
+	return true;
+}
+
+void DocStringTagParser::checkParameters(
+	CallableDeclaration const& _callable,
+	StructurallyDocumented const& _node,
+	StructurallyDocumentedAnnotation& _annotation
+)
+{
+	set<string> validParams;
+	for (auto const& p: _callable.parameters())
+		validParams.insert(p->name());
+	if (_callable.returnParameterList())
+		for (auto const& p: _callable.returnParameterList()->parameters())
+			validParams.insert(p->name());
+	auto paramRange = _annotation.docTags.equal_range("param");
+	for (auto i = paramRange.first; i != paramRange.second; ++i)
+		if (!validParams.count(i->second.paramName))
+			m_errorReporter.docstringParsingError(
+				3881_error,
+				_node.documentation()->location(),
+				"Documented parameter \"" +
+				i->second.paramName +
+				"\" not found in the parameter list of the function."
+			);
+}
+
+void DocStringTagParser::handleConstructor(
+	CallableDeclaration const& _callable,
+	StructurallyDocumented const& _node,
+	StructurallyDocumentedAnnotation& _annotation
+)
+{
+	static set<string> const validTags = set<string>{"author", "dev", "notice", "param"};
+	parseDocStrings(_node, _annotation, validTags, "constructor");
+	checkParameters(_callable, _node, _annotation);
+}
+
+void DocStringTagParser::handleCallable(
+	CallableDeclaration const& _callable,
+	StructurallyDocumented const& _node,
+	StructurallyDocumentedAnnotation& _annotation
+)
+{
+	static set<string> const validEventTags = set<string>{"author", "dev", "notice", "return", "param"};
+	static set<string> const validTags = set<string>{"author", "dev", "notice", "return", "param", "inheritdoc"};
+
+	if (dynamic_cast<EventDefinition const*>(&_callable))
+		parseDocStrings(_node, _annotation, validEventTags, "events");
+	else
+		parseDocStrings(_node, _annotation, validTags, "functions");
+
+	checkParameters(_callable, _node, _annotation);
+
+	if (_node.documentation() && _annotation.docTags.count("author") > 0)
+		m_errorReporter.warning(
+			9843_error, _node.documentation()->location(),
+			"Documentation tag @author is only allowed on contract definitions. "
+			"It will be disallowed in 0.7.0."
+		);
+}
+
+void DocStringTagParser::parseDocStrings(
+	StructurallyDocumented const& _node,
+	StructurallyDocumentedAnnotation& _annotation,
+	set<string> const& _validTags,
+	string const& _nodeName
+)
+{
+	DocStringParser parser;
+	if (_node.documentation() && !_node.documentation()->text()->empty())
+	{
+		parser.parse(*_node.documentation()->text(), m_errorReporter);
+		_annotation.docTags = parser.tags();
+	}
+
+	size_t returnTagsVisited = 0;
+	for (auto const& docTag: _annotation.docTags)
+	{
+		if (!_validTags.count(docTag.first))
+			m_errorReporter.docstringParsingError(
+				6546_error,
+				_node.documentation()->location(),
+				"Documentation tag @" + docTag.first + " not valid for " + _nodeName + "."
+			);
+		else if (docTag.first == "return")
+		{
+			returnTagsVisited++;
+			if (auto const* varDecl = dynamic_cast<VariableDeclaration const*>(&_node))
+			{
+				if (!varDecl->isPublic())
+					m_errorReporter.docstringParsingError(
+						9440_error,
+						_node.documentation()->location(),
+						"Documentation tag \"@" + docTag.first + "\" is only allowed on public state-variables."
+					);
+				if (returnTagsVisited > 1)
+					m_errorReporter.docstringParsingError(
+						5256_error,
+						_node.documentation()->location(),
+						"Documentation tag \"@" + docTag.first + "\" is only allowed once on state-variables."
+					);
+			}
+			else if (auto const* function = dynamic_cast<FunctionDefinition const*>(&_node))
+			{
+				string content = docTag.second.content;
+				string firstWord = content.substr(0, content.find_first_of(" \t"));
+
+				if (returnTagsVisited > function->returnParameters().size())
+					m_errorReporter.docstringParsingError(
+						2604_error,
+						_node.documentation()->location(),
+						"Documentation tag \"@" + docTag.first + " " + docTag.second.content + "\"" +
+						" exceeds the number of return parameters."
+					);
+				else
+				{
+					auto parameter = function->returnParameters().at(returnTagsVisited - 1);
+					if (!parameter->name().empty() && parameter->name() != firstWord)
+						m_errorReporter.docstringParsingError(
+							5856_error,
+							_node.documentation()->location(),
+							"Documentation tag \"@" + docTag.first + " " + docTag.second.content + "\"" +
+							" does not contain the name of its return parameter."
+						);
+				}
+			}
+		}
+	}
+}

libsolidity/analysis/DocStringTagParser.h

@@ -0,0 +1,76 @@
+/*
+	This file is part of solidity.
+
+	solidity is free software: you can redistribute it and/or modify
+	it under the terms of the GNU General Public License as published by
+	the Free Software Foundation, either version 3 of the License, or
+	(at your option) any later version.
+
+	solidity is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU General Public License for more details.
+
+	You should have received a copy of the GNU General Public License
+	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
+*/
+// SPDX-License-Identifier: GPL-3.0
+
+#pragma once
+
+#include <libsolidity/ast/ASTVisitor.h>
+
+namespace solidity::langutil
+{
+class ErrorReporter;
+}
+
+namespace solidity::frontend
+{
+
+/**
+ * Parses the doc tags and does basic validity checks.
+ * Stores the parsing results in the AST annotations and reports errors.
+ */
+class DocStringTagParser: private ASTConstVisitor
+{
+public:
+	explicit DocStringTagParser(langutil::ErrorReporter& _errorReporter): m_errorReporter(_errorReporter) {}
+	bool parseDocStrings(SourceUnit const& _sourceUnit);
+
+private:
+	bool visit(ContractDefinition const& _contract) override;
+	bool visit(FunctionDefinition const& _function) override;
+	bool visit(VariableDeclaration const& _variable) override;
+	bool visit(ModifierDefinition const& _modifier) override;
+	bool visit(EventDefinition const& _event) override;
+
+	void checkParameters(
+		CallableDeclaration const& _callable,
+		StructurallyDocumented const& _node,
+		StructurallyDocumentedAnnotation& _annotation
+	);
+
+	void handleConstructor(
+		CallableDeclaration const& _callable,
+		StructurallyDocumented const& _node,
+		StructurallyDocumentedAnnotation& _annotation
+	);
+
+	void handleCallable(
+		CallableDeclaration const& _callable,
+		StructurallyDocumented const& _node,
+		StructurallyDocumentedAnnotation& _annotation
+	);
+
+	void parseDocStrings(
+		StructurallyDocumented const& _node,
+		StructurallyDocumentedAnnotation& _annotation,
+		std::set<std::string> const& _validTags,
+		std::string const& _nodeName
+	);
+
+	langutil::ErrorReporter& m_errorReporter;
+};
+
+}

libsolidity/analysis/GlobalContext.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @author Gav Wood <g@ethdev.com>

libsolidity/analysis/GlobalContext.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014

libsolidity/analysis/ImmutableValidator.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #include <libsolidity/analysis/ImmutableValidator.h>
 

libsolidity/analysis/ImmutableValidator.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 
 #pragma once
 

libsolidity/analysis/NameAndTypeResolver.cpp

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014

libsolidity/analysis/NameAndTypeResolver.h

@@ -14,6 +14,7 @@
 	You should have received a copy of the GNU General Public License
 	along with solidity.  If not, see <http://www.gnu.org/licenses/>.
 */
+// SPDX-License-Identifier: GPL-3.0
 /**
  * @author Christian <c@ethdev.com>
  * @date 2014