Added NatSpec support for enum value definitions in the AST

Author: veniger

Changelog.md

@@ -7,6 +7,7 @@ Compiler Features:
  * Assembler: Use ``push0`` for placing ``0`` in the stack for EVM versions starting from "Shanghai". This decreases the deployment costs.
  * EVM: Support for the EVM Version "Shanghai".
  * NatSpec: Add support for NatSpec documentation in ``enum`` definitions.
+ * NatSpec: Add support for NatSpec documentation in ``enum`` value definitions.
  * NatSpec: Add support for NatSpec documentation in ``struct`` definitions.
  * NatSpec: Include NatSpec from events that are emitted by a contract but defined outside of it in userdoc and devdoc output.
  * Optimizer: Re-implement simplified version of UnusedAssignEliminator and UnusedStoreEliminator. It can correctly remove some unused assignments in deeply nested loops that were ignored by the old version.

libsolidity/ast/AST.h

@@ -780,11 +780,11 @@ 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

@@ -411,6 +411,7 @@ bool ASTJsonExporter::visit(EnumValue const& _node)
 	setJsonNode(_node, "EnumValue", {
 		make_pair("name", _node.name()),
 		make_pair("nameLocation", sourceLocationToString(_node.nameLocation())),
+		make_pair("documentation", _node.documentation() ? toJson(*_node.documentation()) : Json::nullValue)
 	});
 	return false;
 }

libsolidity/ast/ASTJsonImporter.cpp

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

libsolidity/parsing/Parser.cpp

@@ -701,8 +701,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_definition_natspec.json

@@ -0,0 +1,48 @@
+{
+  "absolutePath": "a",
+  "exportedSymbols":
+  {
+    "Color":
+    [
+      4
+    ]
+  },
+  "id": 5,
+  "nodeType": "SourceUnit",
+  "nodes":
+  [
+    {
+      "canonicalName": "Color",
+      "id": 4,
+      "members":
+      [
+        {
+          "id": 1,
+          "name": "Red",
+          "nameLocation": "17:3:1",
+          "nodeType": "EnumValue",
+          "src": "17:3:1"
+        },
+        {
+          "documentation":
+          {
+            "id": 2,
+            "nodeType": "StructuredDocumentation",
+            "src": "22:111:1",
+            "text": "@title example of title\n @author example of author\n @notice example of notice\n @dev example of dev"
+          },
+          "id": 3,
+          "name": "Green",
+          "nameLocation": "138:5:1",
+          "nodeType": "EnumValue",
+          "src": "138:5:1"
+        }
+      ],
+      "name": "Color",
+      "nameLocation": "5:5:1",
+      "nodeType": "EnumDefinition",
+      "src": "0:145:1"
+    }
+  ],
+  "src": "0:146:1"
+}

test/libsolidity/ASTJSON/enum_value_definition_natspec.sol

@@ -0,0 +1,10 @@
+enum Color {
+    Red,
+/// @title example of title
+/// @author example of author
+/// @notice example of notice
+/// @dev example of dev
+    Green
+}
+
+// ----

test/libsolidity/ASTJSON/enum_value_definition_natspec_parseOnly.json

@@ -0,0 +1,40 @@
+{
+  "absolutePath": "a",
+  "id": 5,
+  "nodeType": "SourceUnit",
+  "nodes":
+  [
+    {
+      "id": 4,
+      "members":
+      [
+        {
+          "id": 1,
+          "name": "Red",
+          "nameLocation": "17:3:1",
+          "nodeType": "EnumValue",
+          "src": "17:3:1"
+        },
+        {
+          "documentation":
+          {
+            "id": 2,
+            "nodeType": "StructuredDocumentation",
+            "src": "22:111:1",
+            "text": "@title example of title\n @author example of author\n @notice example of notice\n @dev example of dev"
+          },
+          "id": 3,
+          "name": "Green",
+          "nameLocation": "138:5:1",
+          "nodeType": "EnumValue",
+          "src": "138:5:1"
+        }
+      ],
+      "name": "Color",
+      "nameLocation": "5:5:1",
+      "nodeType": "EnumDefinition",
+      "src": "0:145:1"
+    }
+  ],
+  "src": "0:146:1"
+}

test/libsolidity/SolidityNatspecJSON.cpp

@@ -1548,6 +1548,41 @@ BOOST_AUTO_TEST_CASE(enum_no_docs)
 	checkNatspec(sourceCode, "C", userDoc, true);
 }
 
+BOOST_AUTO_TEST_CASE(enum_value_no_docs)
+{
+	char const* sourceCode = R"(
+		contract C {
+			enum Color {
+				Red,
+				/// @title example of title
+				/// @author example of author
+				/// @notice example of notice
+				/// @dev example of dev
+				Green
+			}
+
+		}
+	)";
+
+	char const* devDoc = R"ABCDEF(
+	{
+		"kind": "dev",
+		"methods": {},
+		"version": 1
+	})ABCDEF";
+
+	checkNatspec(sourceCode, "C", devDoc, false);
+
+	char const* userDoc = R"ABCDEF(
+	{
+		"kind": "user",
+		"methods": {},
+		"version": 1
+	})ABCDEF";
+
+	checkNatspec(sourceCode, "C", userDoc, true);
+}
+
 BOOST_AUTO_TEST_CASE(natspec_notice_without_tag)
 {
 	char const* sourceCode = R"(

test/libsolidity/syntaxTests/natspec/docstring_enum_value_definition.sol

@@ -0,0 +1,11 @@
+contract C {
+	enum Color {
+		Red,
+		/// @title example of title
+		/// @author example of author
+		/// @notice example of notice
+		/// @dev example of dev
+		Green
+	}
+}
+// ----