diff --git a/Changelog.md b/Changelog.md index 7efefca02d6a..525ed2d9e58b 100644 --- a/Changelog.md +++ b/Changelog.md @@ -4,6 +4,7 @@ Language Features: Compiler Features: +* NatSpec: Capture Natspec documentation of `enum` values in the AST. Bugfixes: diff --git a/docs/natspec-format.rst b/docs/natspec-format.rst index 2f0d1d6b40d9..40da3e5e3529 100644 --- a/docs/natspec-format.rst +++ b/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 =============== ====================================================================================== ============================= diff --git a/libsolidity/ast/AST.h b/libsolidity/ast/AST.h index 0121bef332df..9c7cbbded2cc 100644 --- a/libsolidity/ast/AST.h +++ b/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 const& _name): - Declaration(_id, _location, _name, _location) {} + EnumValue( + int64_t _id, + SourceLocation const& _location, + ASTPointer const& _name, + ASTPointer _documentation + ): + Declaration(_id, _location, _name, _location), + StructurallyDocumented(std::move(_documentation)) + { + } void accept(ASTVisitor& _visitor) override; void accept(ASTConstVisitor& _visitor) const override; diff --git a/libsolidity/ast/ASTJsonExporter.cpp b/libsolidity/ast/ASTJsonExporter.cpp index 42627b5f7f7c..4eaa558713a7 100644 --- a/libsolidity/ast/ASTJsonExporter.cpp +++ b/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; } diff --git a/libsolidity/ast/ASTJsonImporter.cpp b/libsolidity/ast/ASTJsonImporter.cpp index d6cd7f43896a..2d2b66fd8d08 100644 --- a/libsolidity/ast/ASTJsonImporter.cpp +++ b/libsolidity/ast/ASTJsonImporter.cpp @@ -489,7 +489,8 @@ ASTPointer ASTJsonImporter::createEnumValue(Json const& _node) { return createASTNode( _node, - memberAsASTString(_node, "name") + memberAsASTString(_node, "name"), + _node.contains("documentation") && !_node["documentation"].is_null() ? createDocumentation(member(_node, "documentation")) : nullptr ); } diff --git a/libsolidity/parsing/Parser.cpp b/libsolidity/parsing/Parser.cpp index 08a319b5b597..8889e65087fa 100644 --- a/libsolidity/parsing/Parser.cpp +++ b/libsolidity/parsing/Parser.cpp @@ -824,8 +824,9 @@ ASTPointer Parser::parseEnumValue() { RecursionGuard recursionGuard(*this); ASTNodeFactory nodeFactory(*this); + ASTPointer documentation = parseStructuredDocumentation(); nodeFactory.markEndPosition(); - return nodeFactory.createNode(expectIdentifierToken()); + return nodeFactory.createNode(expectIdentifierToken(), documentation); } ASTPointer Parser::parseEnumDefinition() diff --git a/test/libsolidity/ASTJSON/enum_value_natspec.json b/test/libsolidity/ASTJSON/enum_value_natspec.json new file mode 100644 index 000000000000..e468bb987064 --- /dev/null +++ b/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" +} diff --git a/test/libsolidity/ASTJSON/enum_value_natspec.sol b/test/libsolidity/ASTJSON/enum_value_natspec.sol new file mode 100644 index 000000000000..e5209d644831 --- /dev/null +++ b/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 +} + +// ---- diff --git a/test/libsolidity/ASTJSON/enum_value_natspec_parseOnly.json b/test/libsolidity/ASTJSON/enum_value_natspec_parseOnly.json new file mode 100644 index 000000000000..ff3d7c756ed1 --- /dev/null +++ b/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" +} diff --git a/test/libsolidity/natspecJSON/enum_no_docs.sol b/test/libsolidity/natspecJSON/enum.sol similarity index 100% rename from test/libsolidity/natspecJSON/enum_no_docs.sol rename to test/libsolidity/natspecJSON/enum.sol diff --git a/test/libsolidity/natspecJSON/docstring_enum.sol b/test/libsolidity/natspecJSON/enum_value.sol similarity index 55% rename from test/libsolidity/natspecJSON/docstring_enum.sol rename to test/libsolidity/natspecJSON/enum_value.sol index d5ace6b14192..ccb3233a51b4 100644 --- a/test/libsolidity/natspecJSON/docstring_enum.sol +++ b/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 } } // ----