Solidity-docgen v0.2.0-alpha.1 parses only `dev` tags

Support Contracts
1

The only tag parsed by solidity-docgen v0.2.0-alpha.1 is the dev tag, in file extract.js line 185:

  const matches = documentation.match(/^@dev[\t-\r \xA0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]+((?:(?!^@[0-9A-Z_a-z]+)[\0-\uFFFF])*)/m);

Are there any plans to extend this any time soon to support the other tags, such as title, param, return and notice?

Thanks

1 Like
2

Thanks for asking @barakman!

We initially didn’t include @param and @return because we had always felt that the information provided there was redundant with what was explained in prose in @dev, so we decided to use only the latter. How do you deal with this redundancy in your own project? I’m talking about stuff like:

@dev Transfers tokens from `sender` to `recipient`.
@param sender The account to transfer tokens from
@param recipient The account to transfer tokens to

After experimenting with using only @dev in our new docs, though, we do think that more structured documentation of function arguments could be valuable, say in the form of a table or something, below the full prose. We still don’t know exactly what information we’d put there, but it probably makes sense for solidity-docgen to allow using it.

@nventuro What are your thoughts on @param documentation?

1 Like
3

@frangio: Hi.
Thank you for your quick response.

I believe that the param info is in fact very much needed.
Perhaps not in the example that you provided, but in most other cases it is definitely something that I’d like to have in my official documentation.
Moreover, having it parsed on your side would give me the flexibility to incorporate the param info and the dev info in any way that I choose.

AFAIK, on-chain developers who are punctilious, take this part of the documentation quite seriously, and in every audit that I had, the auditing party was very explicit about the necessity of this as part of the smart-contract documentation.

So it would us help a lot if you added this tag to your parsing method.

Thank you very much, and since solidity-docgen is already integrated into out system (see https://github.com/bancorprotocol/contracts/tree/fix_path_to_contracts), I’d be more than happy in helping you to test any updates.

2 Likes
4

Thanks for sharing your thoughts on this issue!

Can you share an example of information that you would write in @param?

1 Like
5

@frangio:

For example: any bool parameter, where you’d need to specify what the true value stands for and what the false value stands for. More generally, this applies to any enum parameter.

Another example is when you need to specify the denomination of a given parameter (i.e., what is the basic unit that this parameter specifies).

Would you like me to share actual cases from our GitHub repo?

Thanks

1 Like
6

Thanks @barakman

If you could share some GitHub examples from your repo using the full range of tags, that would be awesome.

7

Sure, see BancorNetwork.sol.

You can start from line 136 and then scroll down gradually. There are several functions there, which require us to specify the @param tag for each input parameter.

Also, please note that we will likely add a @title tag at the top of this file (the description is already there, just not yet tagged properly).

Thanks

1 Like
8

I think including @param can improve the quality of the documentation.

The new Remix Solidity Documentation Generator plugin creates a table for parameters with name, type and description.

@barakman’s sample from BancorNetwork.sol looks to be a great example of where a table of parameters generated from solidity-docgen would be useful.

    /**
        @dev validates xConvert call by verifying the path format, claiming the callers tokens (if not ETH),
        and verifying the gas price limit
        @param _path        conversion path, see conversion path format above
        @param _amount      amount to convert from (in the initial source token)
        @param _block       if the current block exceeded the given parameter - it is cancelled
        @param _v           (signature[128:130]) associated with the signer address and helps to validate if the signature is legit
        @param _r           (signature[0:64]) associated with the signer address and helps to validate if the signature is legit
        @param _s           (signature[64:128]) associated with the signer address and helps to validate if the signature is legit
    */
    function validateXConversion(
        IERC20Token[] _path,
        uint256 _amount,
        uint256 _block,
        uint8 _v,
        bytes32 _r,
        bytes32 _s
    ) 
        private 
        validConversionPath(_path)    
    {
        // if ETH is provided, ensure that the amount is identical to _amount and verify that the source token is an ether token
        IERC20Token fromToken = _path[0];
        require(msg.value == 0 || (_amount == msg.value && etherTokens[fromToken]));

        // require that the dest token is BNT
        require(_path[_path.length - 1] == registry.addressOf(ContractIds.BNT_TOKEN));

        // if ETH was sent with the call, the source is an ether token - deposit the ETH in it
        // otherwise, we claim the tokens from the sender
        if (msg.value > 0) {
            IEtherToken(fromToken).deposit.value(msg.value)();
        } else {
            ensureTransferFrom(fromToken, msg.sender, this, _amount);
        }

        // verify gas price limit
        if (_v == 0x0 && _r == 0x0 && _s == 0x0) {
            IBancorGasPriceLimit gasPriceLimit = IBancorGasPriceLimit(registry.addressOf(ContractIds.BANCOR_GAS_PRICE_LIMIT));
            gasPriceLimit.validateGasPrice(tx.gasprice);
        } else {
            require(verifyTrustedSender(_path, _amount, _block, msg.sender, _v, _r, _s));
        }
    }
1 Like
9

For reference here, this is the issue where we’re tracking this.

1 Like