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
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
@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
Thanks for sharing your thoughts on this issue!
Can you share an example of information that you would write in @param
?
1 Like
@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
Thanks @barakman
If you could share some GitHub examples from your repo using the full range of tags, that would be awesome.
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
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
For reference here, this is the issue where we’re tracking this.
1 Like