Added NatSpec documentation to the User Defined Value Type definition…

… AST node
ethereum · May 22, 2023 · ec84360 · ec84360
1 parent 02a07fd
commit ec84360
Show file tree

Hide file tree

Showing 10 changed files with 132 additions and 5 deletions.
diff --git a/Changelog.md b/Changelog.md
@@ -6,6 +6,7 @@ Language Features:
 Compiler Features:
  * EWasm: Remove EWasm backend.
  * 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.
+ * NatSpec: Add support for NatSpec documentation in UDVT definitions.
 
 
 Bugfixes:

diff --git a/libsolidity/ast/AST.h b/libsolidity/ast/AST.h
@@ -803,17 +803,19 @@ class EnumValue: public Declaration
  * User defined value types, i.e., custom types, for example, `type MyInt is int`. Allows creating a
  * zero cost abstraction over value type with stricter type requirements.
  */
-class UserDefinedValueTypeDefinition: public Declaration
+class UserDefinedValueTypeDefinition: public Declaration, public StructurallyDocumented
 {
 public:
 	UserDefinedValueTypeDefinition(
 		int64_t _id,
 		SourceLocation const& _location,
 		ASTPointer<ASTString> _name,
 		SourceLocation _nameLocation,
-		ASTPointer<TypeName> _underlyingType
+		ASTPointer<TypeName> _underlyingType,
+		ASTPointer<StructuredDocumentation> _documentation
 	):
 		Declaration(_id, _location, _name, std::move(_nameLocation), Visibility::Default),
+		StructurallyDocumented(std::move(_documentation)),
 		m_underlyingType(std::move(_underlyingType))
 	{
 	}

diff --git a/libsolidity/ast/ASTJsonExporter.cpp b/libsolidity/ast/ASTJsonExporter.cpp
@@ -424,7 +424,8 @@ bool ASTJsonExporter::visit(UserDefinedValueTypeDefinition const& _node)
 	std::vector<pair<string, Json::Value>> attributes = {
 		make_pair("name", _node.name()),
 		make_pair("nameLocation", sourceLocationToString(_node.nameLocation())),
-		make_pair("underlyingType", toJson(*_node.underlyingType()))
+		make_pair("underlyingType", toJson(*_node.underlyingType())),
+		make_pair("documentation", _node.documentation() ? toJson(*_node.documentation()) : Json::nullValue)
 	};
 	addIfSet(attributes, "canonicalName", _node.annotation().canonicalName);
 

diff --git a/libsolidity/ast/ASTJsonImporter.cpp b/libsolidity/ast/ASTJsonImporter.cpp
@@ -486,7 +486,8 @@ ASTPointer<UserDefinedValueTypeDefinition> ASTJsonImporter::createUserDefinedVal
 		_node,
 		memberAsASTString(_node, "name"),
 		createNameSourceLocation(_node),
-		convertJsonToASTNode<TypeName>(member(_node, "underlyingType"))
+		convertJsonToASTNode<TypeName>(member(_node, "underlyingType")),
+		_node["documentation"].isNull() ? nullptr : createDocumentation(member(_node, "documentation"))
 	);
 }
 

diff --git a/libsolidity/parsing/Parser.cpp b/libsolidity/parsing/Parser.cpp
@@ -1101,6 +1101,7 @@ ASTPointer<UserDefinedTypeName> Parser::parseUserDefinedTypeName()
 ASTPointer<UserDefinedValueTypeDefinition> Parser::parseUserDefinedValueTypeDefinition()
 {
 	ASTNodeFactory nodeFactory(*this);
+	ASTPointer<StructuredDocumentation> documentation = parseStructuredDocumentation();
 	expectToken(Token::Type);
 	auto&& [name, nameLocation] = expectIdentifierWithLocation();
 	expectToken(Token::Is);
@@ -1110,7 +1111,8 @@ ASTPointer<UserDefinedValueTypeDefinition> Parser::parseUserDefinedValueTypeDefi
 	return nodeFactory.createNode<UserDefinedValueTypeDefinition>(
 		name,
 		std::move(nameLocation),
-		typeName
+		typeName,
+		std::move(documentation)
 	);
 }
 

diff --git a/test/libsolidity/ASTJSON/udvt_definition_natspec.json b/test/libsolidity/ASTJSON/udvt_definition_natspec.json
@@ -0,0 +1,43 @@
+{
+  "absolutePath": "a",
+  "exportedSymbols":
+  {
+    "Price":
+    [
+      3
+    ]
+  },
+  "id": 4,
+  "nodeType": "SourceUnit",
+  "nodes":
+  [
+    {
+      "canonicalName": "Price",
+      "documentation":
+      {
+        "id": 1,
+        "nodeType": "StructuredDocumentation",
+        "src": "0:112:1",
+        "text": "@title example of title\n @author example of author\n @notice example of notice\n @dev example of dev"
+      },
+      "id": 3,
+      "name": "Price",
+      "nameLocation": "117:5:1",
+      "nodeType": "UserDefinedValueTypeDefinition",
+      "src": "112:22:1",
+      "underlyingType":
+      {
+        "id": 2,
+        "name": "uint128",
+        "nodeType": "ElementaryTypeName",
+        "src": "126:7:1",
+        "typeDescriptions":
+        {
+          "typeIdentifier": "t_uint128",
+          "typeString": "uint128"
+        }
+      }
+    }
+  ],
+  "src": "112:23:1"
+}
diff --git a/test/libsolidity/ASTJSON/udvt_definition_natspec.sol b/test/libsolidity/ASTJSON/udvt_definition_natspec.sol
@@ -0,0 +1,7 @@
+/// @title example of title
+/// @author example of author
+/// @notice example of notice
+/// @dev example of dev
+type Price is uint128;
+
+// ----
diff --git a/test/libsolidity/ASTJSON/udvt_definition_natspec_parseOnly.json b/test/libsolidity/ASTJSON/udvt_definition_natspec_parseOnly.json
@@ -0,0 +1,31 @@
+{
+  "absolutePath": "a",
+  "id": 4,
+  "nodeType": "SourceUnit",
+  "nodes":
+  [
+    {
+      "documentation":
+      {
+        "id": 1,
+        "nodeType": "StructuredDocumentation",
+        "src": "0:112:1",
+        "text": "@title example of title\n @author example of author\n @notice example of notice\n @dev example of dev"
+      },
+      "id": 3,
+      "name": "Price",
+      "nameLocation": "117:5:1",
+      "nodeType": "UserDefinedValueTypeDefinition",
+      "src": "112:22:1",
+      "underlyingType":
+      {
+        "id": 2,
+        "name": "uint128",
+        "nodeType": "ElementaryTypeName",
+        "src": "126:7:1",
+        "typeDescriptions": {}
+      }
+    }
+  ],
+  "src": "112:23:1"
+}
diff --git a/test/libsolidity/SolidityNatspecJSON.cpp b/test/libsolidity/SolidityNatspecJSON.cpp
@@ -1479,6 +1479,37 @@ BOOST_AUTO_TEST_CASE(dev_author_at_function)
 	expectNatspecError(sourceCode);
 }
 
+BOOST_AUTO_TEST_CASE(udvt_definition_no_docs)
+{
+	char const* sourceCode = R"(
+		contract C {
+			/// @title example of title
+			/// @author example of author
+			/// @notice example of notice
+			/// @dev example of dev
+			type Price is uint128;
+		}
+	)";
+
+	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(struct_no_docs)
 {
 	char const* sourceCode = R"(

diff --git a/test/libsolidity/syntaxTests/natspec/docstring_udvt_definition.sol b/test/libsolidity/syntaxTests/natspec/docstring_udvt_definition.sol
@@ -0,0 +1,8 @@
+contract C {
+    /// @title example of title
+    /// @author example of author
+    /// @notice example of notice
+    /// @dev example of dev
+    type Price is uint128;
+}
+// ----