cerc-io/solidity
15
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 for events

Browse Source
This commit is contained in:
Harikrishnan Mulackal 2020-05-25 12:13:57 +05:30
parent 062a999e85
commit 4146ff9fcf
4 changed files with 68 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Changelog.md
View File

@ -6,7 +6,7 @@ Language Features:
Compiler Features:
* NatSpec: Add fields "kind" and "version" to the JSON output.
* Commandline Interface: Prevent some incompatible commandline options from being used together.
* NatSpec: Support NatSpec comments on events.
Bugfixes:
* NatSpec: Do not consider ``////`` and ``/***`` as NatSpec comments.

6
docs/natspec-format.rst
View File

@ -85,9 +85,9 @@ Tag
=========== =============================================================================== =============================
``@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
``@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
=========== =============================================================================== =============================

18
libsolidity/interface/Natspec.cpp
View File

@ -36,6 +36,7 @@ Json::Value Natspec::userDocumentation(ContractDefinition const& _contractDef)
{
Json::Value doc;
Json::Value methods(Json::objectValue);
Json::Value events(Json::objectValue);
doc["version"] = Json::Value(c_natspecVersion);
doc["kind"] = Json::Value("user");
@ -80,7 +81,17 @@ Json::Value Natspec::userDocumentation(ContractDefinition const& _contractDef)
}
}
}
for (auto const& event: _contractDef.events())
{
string value = extractDoc(event->annotation().docTags, "notice");
if (!value.empty())
events[event->functionType(true)->externalSignature()]["notice"] = value;
}
doc["methods"] = methods;
if (!events.empty())
doc["events"] = events;
return doc;
}
@ -141,9 +152,16 @@ Json::Value Natspec::devDocumentation(ContractDefinition const& _contractDef)
stateVariables[varDecl->name()]["return"] = extractDoc(varDecl->annotation().docTags, "return");
}
Json::Value events(Json::objectValue);
for (auto const& event: _contractDef.events())
if (auto devDoc = devDocumentation(event->annotation().docTags); !devDoc.empty())
events[event->functionType(true)->externalSignature()] = devDoc;
doc["methods"] = methods;
if (!stateVariables.empty())
doc["stateVariables"] = stateVariables;
if (!events.empty())
doc["events"] = events;
return doc;
}

46
test/libsolidity/SolidityNatspecJSON.cpp
View File

@ -355,6 +355,52 @@ BOOST_AUTO_TEST_CASE(private_state_variable)
checkNatspec(sourceCode, "test", userDoc, true);
}
BOOST_AUTO_TEST_CASE(event)
{
char const* sourceCode = R"(
contract ERC20 {
/// @notice This event is emitted when a transfer occurs.
/// @param from The source account.
/// @param to The destination account.
/// @param amount The amount.
/// @dev A test case!
event Transfer(address indexed from, address indexed to, uint amount);
}
)";
char const* devDoc = R"ABCDEF(
{
"events":
{
"Transfer(address,address,uint256)":
{
"details": "A test case!",
"params":
{
"amount": "The amount.", "from": "The source account.", "to": "The destination account."
}
}
},
"methods": {}
}
)ABCDEF";
checkNatspec(sourceCode, "ERC20", devDoc, false);
char const* userDoc = R"ABCDEF(
{
"events":
{
"Transfer(address,address,uint256)":
{
"notice": "This event is emitted when a transfer occurs."
}
},
"methods": {}
}
)ABCDEF";
checkNatspec(sourceCode, "ERC20", userDoc, true);
}
BOOST_AUTO_TEST_CASE(dev_desc_after_nl)
{
char const* sourceCode = R"(