diff --git a/Changelog.md b/Changelog.md index 2ddf6647e..207a06cab 100644 --- a/Changelog.md +++ b/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. diff --git a/libsolidity/ast/AST.h b/libsolidity/ast/AST.h index 9d754202d..63caac26d 100644 --- a/libsolidity/ast/AST.h +++ b/libsolidity/ast/AST.h @@ -787,11 +787,11 @@ private: /** * 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 da7f76936..7bdaa382f 100644 --- a/libsolidity/ast/ASTJsonExporter.cpp +++ b/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; } diff --git a/libsolidity/ast/ASTJsonImporter.cpp b/libsolidity/ast/ASTJsonImporter.cpp index dd7098aab..1e9e245ca 100644 --- a/libsolidity/ast/ASTJsonImporter.cpp +++ b/libsolidity/ast/ASTJsonImporter.cpp @@ -476,7 +476,8 @@ ASTPointer ASTJsonImporter::createEnumValue(Json::Value const& _node) { return createASTNode( _node, - memberAsASTString(_node, "name") + memberAsASTString(_node, "name"), + _node["documentation"].isNull() ? nullptr : createDocumentation(member(_node, "documentation")) ); } diff --git a/libsolidity/parsing/Parser.cpp b/libsolidity/parsing/Parser.cpp index efbe85448..a4ded1aaf 100644 --- a/libsolidity/parsing/Parser.cpp +++ b/libsolidity/parsing/Parser.cpp @@ -715,8 +715,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_definition_natspec.json b/test/libsolidity/ASTJSON/enum_value_definition_natspec.json new file mode 100644 index 000000000..a00ee4bff --- /dev/null +++ b/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" +} diff --git a/test/libsolidity/ASTJSON/enum_value_definition_natspec.sol b/test/libsolidity/ASTJSON/enum_value_definition_natspec.sol new file mode 100644 index 000000000..742de7cd4 --- /dev/null +++ b/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 +} + +// ---- diff --git a/test/libsolidity/ASTJSON/enum_value_definition_natspec_parseOnly.json b/test/libsolidity/ASTJSON/enum_value_definition_natspec_parseOnly.json new file mode 100644 index 000000000..9f56385f7 --- /dev/null +++ b/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" +} diff --git a/test/libsolidity/SolidityNatspecJSON.cpp b/test/libsolidity/SolidityNatspecJSON.cpp index a54460eb6..a1d9464c3 100644 --- a/test/libsolidity/SolidityNatspecJSON.cpp +++ b/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"( diff --git a/test/libsolidity/syntaxTests/natspec/docstring_enum_value_definition.sol b/test/libsolidity/syntaxTests/natspec/docstring_enum_value_definition.sol new file mode 100644 index 000000000..9521efe48 --- /dev/null +++ b/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 + } +} +// ----