Add support for enum values in NatSpec

Author: nikola-matic

Changelog.md

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

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", _node.documentation() ? toJson(*_node.documentation()) : Json()),
 	});
 	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/enum_no_docs.sol renamed to test/libsolidity/natspecJSON/enum.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
     }
 }
 // ----