Docs: NatSpec and/or style guide should specify how multi-line NatSpec works

[fulldecent]

Regarding: https://docs.soliditylang.org/en/v0.8.4/natspec-format.html

Many people choose to limit source code line lengths to 79 characters wrap (or some other number). This is an identified best practice in the Solidity Style Guide. And comments can (SHOULD!) be more than just several characters. So...

Let's specify how longer comments should work:

//------10--------20--------30--------40--------50--------60--------70--------80

// Is this preferred❓ (align to tags)

/// @notice You can use this to instantiate a complete circus, including some
///         animals that dance, sing and jump.
/// @dev    Animals are instantiated only once each
contract Circus {
}

// Or this❓ (align to tags and params)

/// @notice You can use this to instantiate a complete circus, including some
///         animals that dance, sing and jump.
/// @dev    Animals are instantiated only once each
/// @param  a       the amount of stuff
/// @param  tokenID which token to operate on
function doThing(uint256 a, uint tokenID b) {
}

// Or this❓ (no indent)

/// @notice You can use this to instantiate a complete circus, including some
/// animals that dance, sing and jump.
/// @dev Animals are instantiated only once each
contract Circus {
}

// Or this❓ (indent to tag-end column)

/// @notice You can use this to instantiate a complete circus, including some
///         animals that dance, sing and jump.
/// @dev Animals are instantiated only once each
contract Circus {
}

// Or this❓ (four-space indent)

/// @notice You can use this to instantiate a complete circus, including some
///     animals that dance, sing and jump.
/// @dev Animals are instantiated only once each
contract Circus {
}

// Or this❓ (repeat tag name) (⚠️ this may be ambiguous for @return and others)

/// @notice You can use this to instantiate a complete circus, including some
/// @notice animals that dance, sing and jump.
/// @dev Animals are instantiated only once each
contract Circus {
}

References

• For source code, four-space indenting is preferred.

Discussion

• Align-to-tags should be most familiar to people with experience using Doxygen on various platforms.
• Align-to-tags indentation also has utility in lining up your @params.
• We should specify that any extra indentation spaces will be surpassed from the JSON output.

Recommended work plan:

• Choose our preferred style (recommend align-to-tags-and-params).
• Update all examples in Solidity documentation to use that style.
• Decide if this should be a public recommendation
  • E.g. the /// format is listed before /** in the NatSpec, and all examples use ///, not /**, but we do NOT publicly recommend /// over /**.
• If there is indentation, show in the JSON output how it is truncated. And specify in text how whitespace is truncated in natspec-format.rst.
  • I.e. "/// @notice Hello\n/// world" is "Hello world", not "Hello world" or "Hello\nworld".

[Abhijnan-Bajpai]

Hey @cameel, I would like to work on this issue if it isn't resolved yet. Could I be assigned?

[cameel]

Sure, just be aware that this is a task that requires some discusion and making a decision on which style we should recommend (and if we should recommend a single style at all). I think that submitting a draft PR with a particular proposal is a good way to get that discussion started though so you can go ahead if you want to try. Just be prepared that there might be some going back and forth in the PR before we agree on a final version :)

I'd suggest to start with just describing the style and only updating all the examples when it's clear which style we want (though updating one or two examples might also be a good way to show off the style you choose).

It would also be good to check if there's one clearly preferred style used in contracts found in the wild. Or what existing linters already recommend - I see that for example solhint does not lint natspec yet and there's a very recent feature request from @fulldecent to add support for it: protofire/solhint#298.

[fulldecent]

Thank you for your interest.

Also want to note my main interest in this issue. Overall my goal is that all Solidity functions should be commented, consistently (no dog shedding), by default, and complained loudly when missing, and have consistent/specified interpretation. And when that happens we might hope that a browser-based web3 wallet will make this information available to you every time you sign something.

[AndriianChestnykh]

@fulldecent, is there any progress on the task or it is deprecated now?

[jtakalai]

I think it's not just "style guide" thing; also the compiler should generate correct multi-line spec with the suggested multi-lining!

[github-actions]

This issue has been marked as stale due to inactivity for the last 90 days.
It will be automatically closed in 7 days.

[github-actions]

Hi everyone! This issue has been automatically closed due to inactivity.
If you think this issue is still relevant in the latest Solidity version and you have something to contribute, feel free to reopen.
However, unless the issue is a concrete proposal that can be implemented, we recommend starting a language discussion on the forum instead.

[hcheng826]

is there any best practices recommendation for this case?

[fulldecent]

My personal recommendation is still align with tags and params.

But can't say this is universally recognized.