Add support for enum values in NatSpec

Changelog.md

@@ -4,6 +4,7 @@ Language Features:
 
 
 Compiler Features:
+* NatSpec: Capture Natspec documentation of `enum` values in the AST.
 
 
 Bugfixes:

docs/natspec-format.rst

@@ -37,7 +37,7 @@ Documentation Example
 =====================
 
 Documentation is inserted above each ``contract``, ``interface``, ``library``,
-``function``, and ``event`` using the Doxygen notation format.
+``function``, ``enum``, ``enum`` value and ``event`` using the Doxygen notation format.
 A ``public`` state variable is equivalent to a ``function``
 for the purposes of NatSpec.
 
@@ -116,13 +116,13 @@ in the same way as if it were tagged with ``@notice``.
 =============== ====================================================================================== =============================
 Tag                                                                                                    Context
 =============== ====================================================================================== =============================
-``@title``      A title that should describe the contract/interface                                    contract, library, interface, struct, enum
-``@author``     The name of the author                                                                 contract, library, interface, struct, enum
-``@notice``     Explain to an end user what this does                                                  contract, library, interface, function, public state variable, event, struct, enum, error
-``@dev``        Explain to a developer any extra details                                               contract, library, interface, function, state variable, event, struct, enum, error
-``@param``      Documents a parameter just like in Doxygen (must be followed by parameter name)        function, event, error
-``@return``     Documents the return variables of a contract's function                                function, public state variable
-``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, public state variable
+``@title``      A title that should describe the contract/interface                                    contract, library, interface, struct, enum, enum values
+``@author``     The name of the author                                                                 contract, library, interface, struct, enum, enum values
+``@notice``     Explain to an end user what this does                                                  contract, library, interface, function, public state variable, event, struct, enum, enum values error
+``@dev``        Explain to a developer any extra details                                               contract, library, interface, function, state variable, event, struct, enum, enum values, error
+``@param``      Documents a parameter just like in Doxygen (must be followed by parameter name)        function, event, enum values, error
+``@return``     Documents the return variables of a contract's function                                function, enum, enum values, public state variable
+``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, enum, enum values, public state variable
 ``@custom:...`` Custom tag, semantics is application-defined                                           everywhere
 =============== ====================================================================================== =============================
 

libsolidity/ast/AST.h

@@ -823,11 +823,19 @@ class EnumDefinition: public Declaration, public StructurallyDocumented, public
 /**
  * Declaration of an Enum Value
  */
-class EnumValue: public Declaration
+class EnumValue: public Declaration, public StructurallyDocumented
 {
 public:
-	EnumValue(int64_t _id, SourceLocation const& _location, ASTPointer<ASTString> const& _name):
-		Declaration(_id, _location, _name, _location) {}
+	EnumValue(
+		int64_t _id,
+		SourceLocation const& _location,
+		ASTPointer<ASTString> const& _name,
+		ASTPointer<StructuredDocumentation> _documentation
+	):
+		Declaration(_id, _location, _name, _location),
+		StructurallyDocumented(std::move(_documentation))
+	{
+	}
 
 	void accept(ASTVisitor& _visitor) override;
 	void accept(ASTConstVisitor& _visitor) const override;

libsolidity/ast/ASTJsonExporter.cpp

@@ -430,6 +430,7 @@ bool ASTJsonExporter::visit(EnumValue const& _node)
 	setJsonNode(_node, "EnumValue", {
 		std::make_pair("name", _node.name()),
 		std::make_pair("nameLocation", sourceLocationToString(_node.nameLocation())),
+		std::make_pair("documentation", toJson(_node.documentation().get())),
 	});
 	return false;
 }

libsolidity/ast/ASTJsonImporter.cpp

@@ -489,7 +489,8 @@ ASTPointer<EnumValue> ASTJsonImporter::createEnumValue(Json const& _node)
 {
 	return createASTNode<EnumValue>(
 		_node,
-		memberAsASTString(_node, "name")
+		memberAsASTString(_node, "name"),
+		_node.contains("documentation") && !_node["documentation"].is_null() ? createDocumentation(member(_node, "documentation")) : nullptr
 	);
 }
 

libsolidity/parsing/Parser.cpp

@@ -824,8 +824,9 @@ ASTPointer<EnumValue> Parser::parseEnumValue()
 {
 	RecursionGuard recursionGuard(*this);
 	ASTNodeFactory nodeFactory(*this);
+	ASTPointer<StructuredDocumentation> documentation = parseStructuredDocumentation();
 	nodeFactory.markEndPosition();
-	return nodeFactory.createNode<EnumValue>(expectIdentifierToken());
+	return nodeFactory.createNode<EnumValue>(expectIdentifierToken(), documentation);
 }
 
 ASTPointer<EnumDefinition> Parser::parseEnumDefinition()

test/libsolidity/ASTJSON/enum_value_natspec.json

@@ -0,0 +1,56 @@
+{
+  "absolutePath": "a",
+  "exportedSymbols": {
+    "Color": [
+      6
+    ]
+  },
+  "id": 7,
+  "nodeType": "SourceUnit",
+  "nodes": [
+    {
+      "canonicalName": "Color",
+      "id": 6,
+      "members": [
+        {
+          "id": 1,
+          "name": "Red",
+          "nameLocation": "17:3:1",
+          "nodeType": "EnumValue",
+          "src": "17:3:1"
+        },
+        {
+          "documentation": {
+            "id": 2,
+            "nodeType": "StructuredDocumentation",
+            "src": "26:57:1",
+            "text": "@notice example of notice\n @dev example of dev"
+          },
+          "id": 3,
+          "name": "Green",
+          "nameLocation": "88:5:1",
+          "nodeType": "EnumValue",
+          "src": "88:5:1"
+        },
+        {
+          "documentation": {
+            "id": 4,
+            "nodeType": "StructuredDocumentation",
+            "src": "99:23:1",
+            "text": "@dev example of dev"
+          },
+          "id": 5,
+          "name": "Blue",
+          "nameLocation": "127:4:1",
+          "nodeType": "EnumValue",
+          "src": "127:4:1"
+        }
+      ],
+      "name": "Color",
+      "nameLocation": "5:5:1",
+      "nodeType": "EnumDefinition",
+      "src": "0:164:1"
+    }
+  ],
+  "src": "0:165:1"
+}

test/libsolidity/ASTJSON/enum_value_natspec.sol

@@ -0,0 +1,11 @@
+enum Color {
+    Red,
+    /// @notice example of notice
+    /// @dev example of dev
+    Green,
+    /// @dev example of dev
+    Blue
+    /// @dev beyond last value
+}
+
+// ----

test/libsolidity/ASTJSON/enum_value_natspec_parseOnly.json

@@ -0,0 +1,50 @@
+{
+  "absolutePath": "a",
+  "id": 7,
+  "nodeType": "SourceUnit",
+  "nodes": [
+    {
+      "id": 6,
+      "members": [
+        {
+          "id": 1,
+          "name": "Red",
+          "nameLocation": "17:3:1",
+          "nodeType": "EnumValue",
+          "src": "17:3:1"
+        },
+        {
+          "documentation": {
+            "id": 2,
+            "nodeType": "StructuredDocumentation",
+            "src": "26:57:1",
+            "text": "@notice example of notice\n @dev example of dev"
+          },
+          "id": 3,
+          "name": "Green",
+          "nameLocation": "88:5:1",
+          "nodeType": "EnumValue",
+          "src": "88:5:1"
+        },
+        {
+          "documentation": {
+            "id": 4,
+            "nodeType": "StructuredDocumentation",
+            "src": "99:23:1",
+            "text": "@dev example of dev"
+          },
+          "id": 5,
+          "name": "Blue",
+          "nameLocation": "127:4:1",
+          "nodeType": "EnumValue",
+          "src": "127:4:1"
+        }
+      ],
+      "name": "Color",
+      "nameLocation": "5:5:1",
+      "nodeType": "EnumDefinition",
+      "src": "0:164:1"
+    }
+  ],
+  "src": "0:165:1"
+}

test/libsolidity/natspecJSON/docstring_enum.sol → test/libsolidity/natspecJSON/enum_value.sol

@@ -1,11 +1,13 @@
 contract C {
-    /// @title example of title
-    /// @author example of author
-    /// @notice example of notice
-    /// @dev example of dev
     enum Color {
+        /// @custom red color
         Red,
+        /// @title example of title
+        /// @author example of author
+        /// @notice example of notice
+        /// @dev example of dev
         Green
+        /// @notice beyond last value
     }
 }
 // ----