NatSpec for events

Changelog.md

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

docs/natspec-format.rst

@@ -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
+``@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
 =========== =============================================================================== =============================
 

libsolidity/interface/Natspec.cpp

@@ -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;
 }

test/libsolidity/SolidityNatspecJSON.cpp

@@ -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"(