cerc-io/solidity
11
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #8532 from aarlt/structured-docs-variables-aarlt

Browse Source 
Allow NatSpec comments for state variables
This commit is contained in:
chriseth
2020-05-19 19:26:35 +02:00
committed by GitHub
parent d1512223d2 af8bb5fb60
commit 22d5caa979
23 changed files with 384 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files
test/libsolidity/ASTJSON/documentation.json
+89 -50
View File
@@ -87,10 +87,10 @@
{
"C":
[
20
23
]
},
"id": 21,
"id": 24,
"license": null,
"nodeType": "SourceUnit",
"nodes":
@@ -102,90 +102,129 @@
"contractKind": "contract",
"documentation": null,
"fullyImplemented": true,
"id": 20,
"id": 23,
"linearizedBaseContracts":
[
20
23
],
"name": "C",
"nodeType": "ContractDefinition",
"nodes":
[
{
"anonymous": false,
"constant": false,
"documentation":
{
"id": 7,
"nodeType": "StructuredDocumentation",
"src": "15:26:3",
"text": "Some comment on Evt."
"src": "15:32:3",
"text": "Some comment on state var."
},
"functionSelector": "c19d93fb",
"id": 9,
"name": "Evt",
"nodeType": "EventDefinition",
"parameters":
"mutability": "mutable",
"name": "state",
"nodeType": "VariableDeclaration",
"overrides": null,
"scope": 23,
"src": "48:17:3",
"stateVariable": true,
"storageLocation": "default",
"typeDescriptions":
{
"typeIdentifier": "t_uint256",
"typeString": "uint256"
},
"typeName":
{
"id": 8,
"nodeType": "ParameterList",
"parameters": [],
"src": "51:2:3"
"name": "uint",
"nodeType": "ElementaryTypeName",
"src": "48:4:3",
"typeDescriptions":
{
"typeIdentifier": "t_uint256",
"typeString": "uint256"
}
},
"src": "42:12:3"
"value": null,
"visibility": "public"
},
{
"body":
{
"id": 13,
"nodeType": "Block",
"src": "99:6:3",
"statements":
[
{
"id": 12,
"nodeType": "PlaceholderStatement",
"src": "101:1:3"
}
]
},
"anonymous": false,
"documentation":
{
"id": 10,
"nodeType": "StructuredDocumentation",
"src": "57:26:3",
"text": "Some comment on mod."
"src": "69:26:3",
"text": "Some comment on Evt."
},
"id": 14,
"name": "mod",
"nodeType": "ModifierDefinition",
"overrides": null,
"id": 12,
"name": "Evt",
"nodeType": "EventDefinition",
"parameters":
{
"id": 11,
"nodeType": "ParameterList",
"parameters": [],
"src": "96:2:3"
"src": "105:2:3"
},
"src": "84:21:3",
"src": "96:12:3"
},
{
"body":
{
"id": 16,
"nodeType": "Block",
"src": "153:6:3",
"statements":
[
{
"id": 15,
"nodeType": "PlaceholderStatement",
"src": "155:1:3"
}
]
},
"documentation":
{
"id": 13,
"nodeType": "StructuredDocumentation",
"src": "111:26:3",
"text": "Some comment on mod."
},
"id": 17,
"name": "mod",
"nodeType": "ModifierDefinition",
"overrides": null,
"parameters":
{
"id": 14,
"nodeType": "ParameterList",
"parameters": [],
"src": "150:2:3"
},
"src": "138:21:3",
"virtual": false,
"visibility": "internal"
},
{
"body":
{
"id": 18,
"id": 21,
"nodeType": "Block",
"src": "155:2:3",
"src": "209:2:3",
"statements": []
},
"documentation":
{
"id": 15,
"id": 18,
"nodeType": "StructuredDocumentation",
"src": "108:25:3",
"src": "162:25:3",
"text": "Some comment on fn."
},
"functionSelector": "a4a2c40b",
"id": 19,
"id": 22,
"implemented": true,
"kind": "function",
"modifiers": [],
@@ -194,29 +233,29 @@
"overrides": null,
"parameters":
{
"id": 16,
"id": 19,
"nodeType": "ParameterList",
"parameters": [],
"src": "145:2:3"
"src": "199:2:3"
},
"returnParameters":
{
"id": 17,
"id": 20,
"nodeType": "ParameterList",
"parameters": [],
"src": "155:0:3"
"src": "209:0:3"
},
"scope": 20,
"src": "134:23:3",
"scope": 23,
"src": "188:23:3",
"stateMutability": "nonpayable",
"virtual": false,
"visibility": "public"
}
],
"scope": 21,
"src": "0:159:3"
"scope": 24,
"src": "0:213:3"
}
],
"src": "0:160:3"
"src": "0:214:3"
}
]
test/libsolidity/ASTJSON/documentation.sol
+1
View File
@@ -11,6 +11,7 @@ contract C {}
// ---- SOURCE: c
contract C {
/** Some comment on state var.*/ uint public state;
/** Some comment on Evt.*/ event Evt();
/** Some comment on mod.*/ modifier mod() { _; }
/** Some comment on fn.*/ function fn() public {}
test/libsolidity/ASTJSON/documentation_legacy.json
+75 -34
View File
@@ -6,7 +6,7 @@
{
"C":
[
20
23
]
},
"license": null
@@ -30,13 +30,54 @@
"fullyImplemented": true,
"linearizedBaseContracts":
[
20
23
],
"name": "C",
"scope": 21
"scope": 24
},
"children":
[
{
"attributes":
{
"constant": false,
"functionSelector": "c19d93fb",
"mutability": "mutable",
"name": "state",
"overrides": null,
"scope": 23,
"stateVariable": true,
"storageLocation": "default",
"type": "uint256",
"value": null,
"visibility": "public"
},
"children":
[
{
"attributes":
{
"name": "uint",
"type": "uint256"
},
"id": 8,
"name": "ElementaryTypeName",
"src": "48:4:3"
},
{
"attributes":
{
"text": "Some comment on state var."
},
"id": 7,
"name": "StructuredDocumentation",
"src": "15:32:3"
}
],
"id": 9,
"name": "VariableDeclaration",
"src": "48:17:3"
},
{
"attributes":
{
@@ -50,9 +91,9 @@
{
"text": "Some comment on Evt."
},
"id": 7,
"id": 10,
"name": "StructuredDocumentation",
"src": "15:26:3"
"src": "69:26:3"
},
{
"attributes":
@@ -63,14 +104,14 @@
]
},
"children": [],
"id": 8,
"id": 11,
"name": "ParameterList",
"src": "51:2:3"
"src": "105:2:3"
}
],
"id": 9,
"id": 12,
"name": "EventDefinition",
"src": "42:12:3"
"src": "96:12:3"
},
{
"attributes":
@@ -87,9 +128,9 @@
{
"text": "Some comment on mod."
},
"id": 10,
"id": 13,
"name": "StructuredDocumentation",
"src": "57:26:3"
"src": "111:26:3"
},
{
"attributes":
@@ -100,27 +141,27 @@
]
},
"children": [],
"id": 11,
"id": 14,
"name": "ParameterList",
"src": "96:2:3"
"src": "150:2:3"
},
{
"children":
[
{
"id": 12,
"id": 15,
"name": "PlaceholderStatement",
"src": "101:1:3"
"src": "155:1:3"
}
],
"id": 13,
"id": 16,
"name": "Block",
"src": "99:6:3"
"src": "153:6:3"
}
],
"id": 14,
"id": 17,
"name": "ModifierDefinition",
"src": "84:21:3"
"src": "138:21:3"
},
{
"attributes":
@@ -135,7 +176,7 @@
],
"name": "fn",
"overrides": null,
"scope": 20,
"scope": 23,
"stateMutability": "nonpayable",
"virtual": false,
"visibility": "public"
@@ -147,9 +188,9 @@
{
"text": "Some comment on fn."
},
"id": 15,
"id": 18,
"name": "StructuredDocumentation",
"src": "108:25:3"
"src": "162:25:3"
},
{
"attributes":
@@ -160,9 +201,9 @@
]
},
"children": [],
"id": 16,
"id": 19,
"name": "ParameterList",
"src": "145:2:3"
"src": "199:2:3"
},
{
"attributes":
@@ -173,9 +214,9 @@
]
},
"children": [],
"id": 17,
"id": 20,
"name": "ParameterList",
"src": "155:0:3"
"src": "209:0:3"
},
{
"attributes":
@@ -186,22 +227,22 @@
]
},
"children": [],
"id": 18,
"id": 21,
"name": "Block",
"src": "155:2:3"
"src": "209:2:3"
}
],
"id": 19,
"id": 22,
"name": "FunctionDefinition",
"src": "134:23:3"
"src": "188:23:3"
}
],
"id": 20,
"id": 23,
"name": "ContractDefinition",
"src": "0:159:3"
"src": "0:213:3"
}
],
"id": 21,
"id": 24,
"name": "SourceUnit",
"src": "0:160:3"
"src": "0:214:3"
}
test/libsolidity/SolidityNatspecJSON.cpp
+71
View File
@@ -204,6 +204,77 @@ BOOST_AUTO_TEST_CASE(dev_and_user_no_doc)
checkNatspec(sourceCode, "test", userNatspec, true);
}
BOOST_AUTO_TEST_CASE(public_state_variable)
{
char const* sourceCode = R"(
contract test {
/// @notice example of notice
/// @dev example of dev
/// @return returns state
uint public state;
}
)";
char const* devDoc = R"R(
{
"methods" : {},
"stateVariables" :
{
"state" :
{
"details" : "example of dev",
"return" : "returns state"
}
}
}
)R";
checkNatspec(sourceCode, "test", devDoc, false);
char const* userDoc = R"R(
{
"methods" :
{
"state()" :
{
"notice": "example of notice"
}
}
}
)R";
checkNatspec(sourceCode, "test", userDoc, true);
}
BOOST_AUTO_TEST_CASE(private_state_variable)
{
char const* sourceCode = R"(
contract test {
/// @dev example of dev
uint private state;
}
)";
char const* devDoc = R"(
{
"methods" : {},
"stateVariables" :
{
"state" :
{
"details" : "example of dev"
}
}
}
)";
checkNatspec(sourceCode, "test", devDoc, false);
char const* userDoc = R"(
{
"methods":{}
}
)";
checkNatspec(sourceCode, "test", userDoc, true);
}
BOOST_AUTO_TEST_CASE(dev_desc_after_nl)
{
char const* sourceCode = R"(
test/libsolidity/syntaxTests/natspec/docstring_author_title_state_variable.sol
+7
View File
@@ -0,0 +1,7 @@
contract C {
/// @title title
/// @author author
uint private state;
}
// ----
// Warning: (17-56): Documentation tag @title and @author is only allowed on contract definitions. It will be disallowed in 0.7.0.
test/libsolidity/syntaxTests/natspec/docstring_non_public_state_variable_with_return.sol
+6
View File
@@ -0,0 +1,6 @@
contract test {
/// @return returns something
uint private state;
}
// ----
// DocstringParsingError: (18-47): Documentation tag "@return" is only allowed on public state-variables.
test/libsolidity/syntaxTests/natspec/docstring_private_state_variable.sol
+7
View File
@@ -0,0 +1,7 @@
contract C {
/// @notice example of notice
/// @dev example of dev
uint private state;
}
// ----
// Warning: (17-74): Documentation tag on non-public state variables will be disallowed in 0.7.0. You will need to use the @dev tag explicitly.
test/libsolidity/syntaxTests/natspec/docstring_state_variable.sol
+5
View File
@@ -0,0 +1,5 @@
contract C {
/// @notice example of notice
/// @dev example of dev
uint public state;
}
test/libsolidity/syntaxTests/natspec/docstring_state_variable_too_many_return_tags.sol
+9
View File
@@ -0,0 +1,9 @@
contract test {
/// @notice example of notice
/// @dev example of dev
/// @return returns something
/// @return returns something
uint public state;
}
// ----
// DocstringParsingError: (18-137): Documentation tag "@return" is only allowed once on state-variables.
test/libsolidity/syntaxTests/natspec/docstring_variable.sol
+14
View File
@@ -0,0 +1,14 @@
contract C {
function f() public pure returns (uint) {
/// @title example of title
/// @author example of author
/// @notice example of notice
/// @dev example of dev
/// @param example of param
/// @return example of return
uint state = 42;
return state;
}
}
// ----
// Warning: (290-295): Only state variables can have a docstring. This will be disallowed in 0.7.0.