Added NatSpec support for enum value definitions in the AST

Changelog.md

@@ -8,6 +8,7 @@ Compiler Features:
  * Commandline Interface: Add ``--ir-ast-json`` and ``--ir-optimized-ast-json`` outputs for Solidity input, providing AST in compact JSON format for IR and optimized IR.
  * Commandline Interface: Respect ``--optimize-yul`` and ``--no-optimize-yul`` in compiler mode and accept them in assembler mode as well. ``--optimize --no-optimize-yul`` combination now allows enabling EVM assembly optimizer without enabling Yul optimizer.
  * EWasm: Remove EWasm backend.
+ * NatSpec: Add support for NatSpec documentation in ``enum`` value definitions.
  * Parser: Introduce ``pragma experimental solidity``, which will enable an experimental language mode that in particular has no stability guarantees between non-breaking releases and is not suited for production use.
  * SMTChecker: Add ``--model-checker-print-query`` CLI option and ``settings.modelChecker.printQuery`` JSON option to output the SMTChecker queries in the SMTLIB2 format. This requires using `smtlib2` solver only.
  * Standard JSON Interface: Add ``ast`` file-level output for Yul input.

libsolidity/ast/AST.h

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

@@ -414,6 +414,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

@@ -476,7 +476,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

@@ -715,8 +715,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,62 @@
+{
+  "absolutePath": "a",
+  "exportedSymbols":
+  {
+    "Color":
+    [
+      6
+    ]
+  },
+  "id": 7,
+  "nodeType": "SourceUnit",
+  "nodes":
+  [
+    {
+      "canonicalName": "Color",
+      "id": 6,
+      "members":
+      [
+        {
+          "id": 1,
+          "name": "Red",
+          "nameLocation": "14:3:1",
+          "nodeType": "EnumValue",
+          "src": "14:3:1"
+        },
+        {
+          "documentation":
+          {
+            "id": 2,
+            "nodeType": "StructuredDocumentation",
+            "src": "20:54:1",
+            "text": "@notice example of notice\n @dev example of dev"
+          },
+          "id": 3,
+          "name": "Green",
+          "nameLocation": "76:5:1",
+          "nodeType": "EnumValue",
+          "src": "76:5:1"
+        },
+        {
+          "documentation":
+          {
+            "id": 4,
+            "nodeType": "StructuredDocumentation",
+            "src": "84:23:1",
+            "text": "@dev example of dev"
+          },
+          "id": 5,
+          "name": "Blue",
+          "nameLocation": "109:4:1",
+          "nodeType": "EnumValue",
+          "src": "109:4:1"
+        }
+      ],
+      "name": "Color",
+      "nameLocation": "5:5:1",
+      "nodeType": "EnumDefinition",
+      "src": "0:115:1"
+    }
+  ],
+  "src": "0:116:1"
+}

test/libsolidity/ASTJSON/enum_value_definition_natspec.sol

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

test/libsolidity/ASTJSON/enum_value_definition_natspec_parseOnly.json

@@ -0,0 +1,54 @@
+{
+  "absolutePath": "a",
+  "id": 7,
+  "nodeType": "SourceUnit",
+  "nodes":
+  [
+    {
+      "id": 6,
+      "members":
+      [
+        {
+          "id": 1,
+          "name": "Red",
+          "nameLocation": "14:3:1",
+          "nodeType": "EnumValue",
+          "src": "14:3:1"
+        },
+        {
+          "documentation":
+          {
+            "id": 2,
+            "nodeType": "StructuredDocumentation",
+            "src": "20:54:1",
+            "text": "@notice example of notice\n @dev example of dev"
+          },
+          "id": 3,
+          "name": "Green",
+          "nameLocation": "76:5:1",
+          "nodeType": "EnumValue",
+          "src": "76:5:1"
+        },
+        {
+          "documentation":
+          {
+            "id": 4,
+            "nodeType": "StructuredDocumentation",
+            "src": "84:23:1",
+            "text": "@dev example of dev"
+          },
+          "id": 5,
+          "name": "Blue",
+          "nameLocation": "109:4:1",
+          "nodeType": "EnumValue",
+          "src": "109:4:1"
+        }
+      ],
+      "name": "Color",
+      "nameLocation": "5:5:1",
+      "nodeType": "EnumDefinition",
+      "src": "0:115:1"
+    }
+  ],
+  "src": "0:116: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,
+		/// @notice example of notice
+		/// @dev example of dev
+		Green,
+		/// @dev example of dev
+		Blue
+	}
+}
+// ----