cerc-io/solidity
16
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Natspec: Add warning when using @author with functions

Browse Source
This commit is contained in:
Mathias Baumann 2020-06-29 13:25:42 +02:00
parent a1309e4c5f
commit fe33891531
3 changed files with 14 additions and 7 deletions
docs
natspec-format.rst
libsolidity/analysis
DocStringAnalyser.cpp
test/libsolidity/syntaxTests/natspec
docstring_author_function.sol

8
docs/natspec-format.rst
View File

@ -42,10 +42,6 @@ The following example shows a contract and a function using all available tags.
.. note:: .. 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 The Solidity compiler only interprets tags if they are external or
public. You are welcome to use similar comments for your internal and public. You are welcome to use similar comments for your internal and
private functions, but those will not be parsed. 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 /// @notice You can use this contract for only the most basic simulation
/// @dev All function calls are currently implemented without side effects /// @dev All function calls are currently implemented without side effects
contract Tree { contract Tree {
/// @author Mary A. Botanist
/// @notice Calculate tree age in years, rounded up, for live trees /// @notice Calculate tree age in years, rounded up, for live trees
/// @dev The Alexandr N. Tetearing algorithm could increase precision /// @dev The Alexandr N. Tetearing algorithm could increase precision
/// @param rings The number of rings from dendrochronological sample /// @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 Tag Context
=========== =============================================================================== ============================= =========== =============================================================================== =============================
``@title`` A title that should describe the contract/interface contract, interface ``@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 ``@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 ``@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 ``@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)" : "age(uint256)" :
{ {
"author" : "Mary A. Botanist",
"details" : "The Alexandr N. Tetearing algorithm could increase precision", "details" : "The Alexandr N. Tetearing algorithm could increase precision",
"params" : "params" :
{ {

7
libsolidity/analysis/DocStringAnalyser.cpp
View File

@ -142,6 +142,13 @@ void DocStringAnalyser::handleCallable(
static set<string> const validTags = set<string>{"author", "dev", "notice", "return", "param"}; static set<string> const validTags = set<string>{"author", "dev", "notice", "return", "param"};
parseDocStrings(_node, _annotation, validTags, "functions"); parseDocStrings(_node, _annotation, validTags, "functions");
checkParameters(_callable, _node, _annotation); 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( void DocStringAnalyser::parseDocStrings(

6
test/libsolidity/syntaxTests/natspec/docstring_author_function.sol Normal file
View File

@ -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.