argotorg / argotorg/solidity

Natspec: change parameters and return values to be an array

Open
#11,120 5 comments 0 reactions 0 assignees View on GitHub
low effort medium impact must have natspec protocol design :crystal_ball:
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.