Natspec: change parameters and return values to be an array
- Dominant language
- C++
- Stars
- 25.7k
- Forks
- 6.2k
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 29
Description
Based on #1141. I thought there was a specific issue, but couldn't find it.
One of the main complaints I had is that parameter handling is not well thought out.
```solidity
/// @param a first
/// @param c third
/// @param b second
function a(uint a, uint c, uint b) {
}
```
```json
{
"methods" : {
"a(uint256,uint256,uint256)" : {
"params" : {
"a" : "first",
"b" : "second",
"c" : "third"
},
}
}
}
```
The problem is that the signature does not contain the name of the parameters, and the `params` field only contains a mapping and not an ordered list. This means JSON libraries are free to order the entries as they wish, potentially changing the order based on the lexicographic value of the key.
The proposal is change to the `params` (and `returns`) to be an array, where each entry is a mapping of `{ name: .., description: ...}`.
Contributor guide
Research direction
Start by reviewing issue #1141 and locating the Natspec JSON generation entry point in the Solidity repository. Trace how parameter and return descriptions are produced, then verify that both fields use ordered arrays with name and description entries and that relevant output checks cover the changed structure.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, solidity
- Domain
- compilers, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100