From fe3389153113679fa934e7fbb0335f562a10433b Mon Sep 17 00:00:00 2001
From: Mathias Baumann <marenz@supradigital.org>
Date: Mon, 29 Jun 2020 13:25:42 +0200
Subject: [PATCH] Natspec: Add warning when using `@author` with functions

---
 docs/natspec-format.rst                                   | 8 +-------
 libsolidity/analysis/DocStringAnalyser.cpp                | 7 +++++++
 .../syntaxTests/natspec/docstring_author_function.sol     | 6 ++++++
 3 files changed, 14 insertions(+), 7 deletions(-)
 create mode 100644 test/libsolidity/syntaxTests/natspec/docstring_author_function.sol

diff --git a/docs/natspec-format.rst b/docs/natspec-format.rst
index d8f847841..ca6776975 100644
--- a/docs/natspec-format.rst
+++ b/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,7 +79,7 @@ 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
+``@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
@@ -193,7 +188,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" :
           {
diff --git a/libsolidity/analysis/DocStringAnalyser.cpp b/libsolidity/analysis/DocStringAnalyser.cpp
index 7d8a8a43f..86c59a2c0 100644
--- a/libsolidity/analysis/DocStringAnalyser.cpp
+++ b/libsolidity/analysis/DocStringAnalyser.cpp
@@ -142,6 +142,13 @@ void DocStringAnalyser::handleCallable(
 	static set<string> const validTags = set<string>{"author", "dev", "notice", "return", "param"};
 	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 DocStringAnalyser::parseDocStrings(
diff --git a/test/libsolidity/syntaxTests/natspec/docstring_author_function.sol b/test/libsolidity/syntaxTests/natspec/docstring_author_function.sol
new file mode 100644
index 000000000..7b6ca862b
--- /dev/null
+++ b/test/libsolidity/syntaxTests/natspec/docstring_author_function.sol
@@ -0,0 +1,6 @@
+contract C {
+    /// @author author
+    function iHaveAuthor() public pure {}
+}
+// ----
+// Warning 9843: (17-35): Documentation tag @author is only allowed on contract definitions. It will be disallowed in 0.7.0.