Skip to content

Commit 949a52f

Browse files
nikola-maticnikola-matic
authored
Merge pull request #15956 from ethereum/make-enums-available-in-natspec
Add support for enum values in NatSpec
2 parents 7a4ddb2 + c4b454a commit 949a52f

File tree

11 files changed

+148
-17
lines changed

11 files changed

+148
-17
lines changed

‎Changelog.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Language Features:
44

55

66
Compiler Features:
7+
* NatSpec: Capture Natspec documentation of `enum` values in the AST.
78

89

910
Bugfixes:

‎docs/natspec-format.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Documentation Example
3737
=====================
3838

3939
Documentation is inserted above each ``contract``, ``interface``, ``library``,
40-
``function``, and ``event`` using the Doxygen notation format.
40+
``function``, ``enum``, ``enum`` value and ``event`` using the Doxygen notation format.
4141
A ``public`` state variable is equivalent to a ``function``
4242
for the purposes of NatSpec.
4343

@@ -116,13 +116,13 @@ in the same way as if it were tagged with ``@notice``.
116116
=============== ====================================================================================== =============================
117117
Tag Context
118118
=============== ====================================================================================== =============================
119-
``@title`` A title that should describe the contract/interface contract, library, interface, struct, enum
120-
``@author`` The name of the author contract, library, interface, struct, enum
121-
``@notice`` Explain to an end user what this does contract, library, interface, function, public state variable, event, struct, enum, error
122-
``@dev`` Explain to a developer any extra details contract, library, interface, function, state variable, event, struct, enum, error
123-
``@param`` Documents a parameter just like in Doxygen (must be followed by parameter name) function, event, error
124-
``@return`` Documents the return variables of a contract's function function, public state variable
125-
``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, public state variable
119+
``@title`` A title that should describe the contract/interface contract, library, interface, struct, enum, enum values
120+
``@author`` The name of the author contract, library, interface, struct, enum, enum values
121+
``@notice`` Explain to an end user what this does contract, library, interface, function, public state variable, event, struct, enum, enum values error
122+
``@dev`` Explain to a developer any extra details contract, library, interface, function, state variable, event, struct, enum, enum values, error
123+
``@param`` Documents a parameter just like in Doxygen (must be followed by parameter name) function, event, enum values, error
124+
``@return`` Documents the return variables of a contract's function function, enum, enum values, public state variable
125+
``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, enum, enum values, public state variable
126126
``@custom:...`` Custom tag, semantics is application-defined everywhere
127127
=============== ====================================================================================== =============================
128128

‎libsolidity/ast/AST.h

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -823,11 +823,19 @@ class EnumDefinition: public Declaration, public StructurallyDocumented, public
823823
/**
824824
* Declaration of an Enum Value
825825
*/
826-
class EnumValue: public Declaration
826+
class EnumValue: public Declaration, public StructurallyDocumented
827827
{
828828
public:
829-
EnumValue(int64_t _id, SourceLocation const& _location, ASTPointer<ASTString> const& _name):
830-
Declaration(_id, _location, _name, _location) {}
829+
EnumValue(
830+
int64_t _id,
831+
SourceLocation const& _location,
832+
ASTPointer<ASTString> const& _name,
833+
ASTPointer<StructuredDocumentation> _documentation
834+
):
835+
Declaration(_id, _location, _name, _location),
836+
StructurallyDocumented(std::move(_documentation))
837+
{
838+
}
831839

832840
void accept(ASTVisitor& _visitor) override;
833841
void accept(ASTConstVisitor& _visitor) const override;

‎libsolidity/ast/ASTJsonExporter.cpp

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -430,6 +430,7 @@ bool ASTJsonExporter::visit(EnumValue const& _node)
430430
setJsonNode(_node, "EnumValue", {
431431
std::make_pair("name", _node.name()),
432432
std::make_pair("nameLocation", sourceLocationToString(_node.nameLocation())),
433+
std::make_pair("documentation", toJson(_node.documentation().get())),
433434
});
434435
return false;
435436
}

‎libsolidity/ast/ASTJsonImporter.cpp

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -489,7 +489,8 @@ ASTPointer<EnumValue> ASTJsonImporter::createEnumValue(Json const& _node)
489489
{
490490
return createASTNode<EnumValue>(
491491
_node,
492-
memberAsASTString(_node, "name")
492+
memberAsASTString(_node, "name"),
493+
_node.contains("documentation") && !_node["documentation"].is_null() ? createDocumentation(member(_node, "documentation")) : nullptr
493494
);
494495
}
495496

‎libsolidity/parsing/Parser.cpp

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -824,8 +824,9 @@ ASTPointer<EnumValue> Parser::parseEnumValue()
824824
{
825825
RecursionGuard recursionGuard(*this);
826826
ASTNodeFactory nodeFactory(*this);
827+
ASTPointer<StructuredDocumentation> documentation = parseStructuredDocumentation();
827828
nodeFactory.markEndPosition();
828-
return nodeFactory.createNode<EnumValue>(expectIdentifierToken());
829+
return nodeFactory.createNode<EnumValue>(expectIdentifierToken(), documentation);
829830
}
830831

831832
ASTPointer<EnumDefinition> Parser::parseEnumDefinition()

‎test/libsolidity/ASTJSON/enum_value_natspec.json

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
{
2+
"absolutePath": "a",
3+
"exportedSymbols": {
4+
"Color": [
5+
6
6+
]
7+
},
8+
"id": 7,
9+
"nodeType": "SourceUnit",
10+
"nodes": [
11+
{
12+
"canonicalName": "Color",
13+
"id": 6,
14+
"members": [
15+
{
16+
"id": 1,
17+
"name": "Red",
18+
"nameLocation": "17:3:1",
19+
"nodeType": "EnumValue",
20+
"src": "17:3:1"
21+
},
22+
{
23+
"documentation": {
24+
"id": 2,
25+
"nodeType": "StructuredDocumentation",
26+
"src": "26:57:1",
27+
"text": "@notice example of notice\n @dev example of dev"
28+
},
29+
"id": 3,
30+
"name": "Green",
31+
"nameLocation": "88:5:1",
32+
"nodeType": "EnumValue",
33+
"src": "88:5:1"
34+
},
35+
{
36+
"documentation": {
37+
"id": 4,
38+
"nodeType": "StructuredDocumentation",
39+
"src": "99:23:1",
40+
"text": "@dev example of dev"
41+
},
42+
"id": 5,
43+
"name": "Blue",
44+
"nameLocation": "127:4:1",
45+
"nodeType": "EnumValue",
46+
"src": "127:4:1"
47+
}
48+
],
49+
"name": "Color",
50+
"nameLocation": "5:5:1",
51+
"nodeType": "EnumDefinition",
52+
"src": "0:164:1"
53+
}
54+
],
55+
"src": "0:165:1"
56+
}

‎test/libsolidity/ASTJSON/enum_value_natspec.sol

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
enum Color {
2+
Red,
3+
/// @notice example of notice
4+
/// @dev example of dev
5+
Green,
6+
/// @dev example of dev
7+
Blue
8+
/// @dev beyond last value
9+
}
10+
11+
// ----

‎test/libsolidity/ASTJSON/enum_value_natspec_parseOnly.json

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"absolutePath": "a",
3+
"id": 7,
4+
"nodeType": "SourceUnit",
5+
"nodes": [
6+
{
7+
"id": 6,
8+
"members": [
9+
{
10+
"id": 1,
11+
"name": "Red",
12+
"nameLocation": "17:3:1",
13+
"nodeType": "EnumValue",
14+
"src": "17:3:1"
15+
},
16+
{
17+
"documentation": {
18+
"id": 2,
19+
"nodeType": "StructuredDocumentation",
20+
"src": "26:57:1",
21+
"text": "@notice example of notice\n @dev example of dev"
22+
},
23+
"id": 3,
24+
"name": "Green",
25+
"nameLocation": "88:5:1",
26+
"nodeType": "EnumValue",
27+
"src": "88:5:1"
28+
},
29+
{
30+
"documentation": {
31+
"id": 4,
32+
"nodeType": "StructuredDocumentation",
33+
"src": "99:23:1",
34+
"text": "@dev example of dev"
35+
},
36+
"id": 5,
37+
"name": "Blue",
38+
"nameLocation": "127:4:1",
39+
"nodeType": "EnumValue",
40+
"src": "127:4:1"
41+
}
42+
],
43+
"name": "Color",
44+
"nameLocation": "5:5:1",
45+
"nodeType": "EnumDefinition",
46+
"src": "0:164:1"
47+
}
48+
],
49+
"src": "0:165:1"
50+
}

‎test/libsolidity/natspecJSON/enum_no_docs.sol renamed to ‎test/libsolidity/natspecJSON/enum.sol

File renamed without changes.

0 commit comments

Comments
 (0)