mirror of
https://github.com/ethereum/solidity
synced 2023-10-03 13:03:40 +00:00
NatSpec for events
This commit is contained in:
parent
062a999e85
commit
4146ff9fcf
@ -6,7 +6,7 @@ Language Features:
|
|||||||
Compiler Features:
|
Compiler Features:
|
||||||
* NatSpec: Add fields "kind" and "version" to the JSON output.
|
* NatSpec: Add fields "kind" and "version" to the JSON output.
|
||||||
* Commandline Interface: Prevent some incompatible commandline options from being used together.
|
* Commandline Interface: Prevent some incompatible commandline options from being used together.
|
||||||
|
* NatSpec: Support NatSpec comments on events.
|
||||||
|
|
||||||
Bugfixes:
|
Bugfixes:
|
||||||
* NatSpec: Do not consider ``////`` and ``/***`` as NatSpec comments.
|
* NatSpec: Do not consider ``////`` and ``/***`` as NatSpec comments.
|
||||||
|
@ -85,9 +85,9 @@ Tag
|
|||||||
=========== =============================================================================== =============================
|
=========== =============================================================================== =============================
|
||||||
``@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, function
|
||||||
``@notice`` Explain to an end user what this does contract, interface, function, public state variable
|
``@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
|
``@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
|
``@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
|
``@return`` Documents the return variables of a contract's function function, public state variable
|
||||||
=========== =============================================================================== =============================
|
=========== =============================================================================== =============================
|
||||||
|
|
||||||
|
@ -36,6 +36,7 @@ Json::Value Natspec::userDocumentation(ContractDefinition const& _contractDef)
|
|||||||
{
|
{
|
||||||
Json::Value doc;
|
Json::Value doc;
|
||||||
Json::Value methods(Json::objectValue);
|
Json::Value methods(Json::objectValue);
|
||||||
|
Json::Value events(Json::objectValue);
|
||||||
|
|
||||||
doc["version"] = Json::Value(c_natspecVersion);
|
doc["version"] = Json::Value(c_natspecVersion);
|
||||||
doc["kind"] = Json::Value("user");
|
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;
|
doc["methods"] = methods;
|
||||||
|
if (!events.empty())
|
||||||
|
doc["events"] = events;
|
||||||
|
|
||||||
return doc;
|
return doc;
|
||||||
}
|
}
|
||||||
@ -141,9 +152,16 @@ Json::Value Natspec::devDocumentation(ContractDefinition const& _contractDef)
|
|||||||
stateVariables[varDecl->name()]["return"] = extractDoc(varDecl->annotation().docTags, "return");
|
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;
|
doc["methods"] = methods;
|
||||||
if (!stateVariables.empty())
|
if (!stateVariables.empty())
|
||||||
doc["stateVariables"] = stateVariables;
|
doc["stateVariables"] = stateVariables;
|
||||||
|
if (!events.empty())
|
||||||
|
doc["events"] = events;
|
||||||
|
|
||||||
return doc;
|
return doc;
|
||||||
}
|
}
|
||||||
|
@ -355,6 +355,52 @@ BOOST_AUTO_TEST_CASE(private_state_variable)
|
|||||||
checkNatspec(sourceCode, "test", userDoc, true);
|
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)
|
BOOST_AUTO_TEST_CASE(dev_desc_after_nl)
|
||||||
{
|
{
|
||||||
char const* sourceCode = R"(
|
char const* sourceCode = R"(
|
||||||
|
Loading…
Reference in New Issue
Block a user