feat(forge doc): include custom natspec

[leovct]

Motivation

Closes #8488

Include @custom natspec tags when rendering docs with forge doc.

Solution

I've chosen to prefix custom tags with // Comment: for visibility reasons, but I'm open to suggestions.

Example with https://github.com/artgobblers/art-gobblers where I introduced some custom tags.

$ git diff src/ArtGobblers.sol
diff --git a/src/ArtGobblers.sol b/src/ArtGobblers.sol
index d322858..71cb8e9 100644
--- a/src/ArtGobblers.sol
+++ b/src/ArtGobblers.sol
@@ -80,6 +80,9 @@ import {Pages} from "./Pages.sol";
 /// @author FrankieIsLost <[email protected]>
 /// @author transmissions11 <[email protected]>
 /// @notice An experimental decentralized art factory by Justin Roiland and Paradigm.
+/// @custom:test-a A first custom tag
+/// @custom:test-b A second custom tag
+/// @custom:test-c A third custom tag
 contract ArtGobblers is GobblersERC721, LogisticVRGDA, Owned, ERC1155TokenReceiver {
     using LibString for uint256;
     using FixedPointMathLib for uint256;
@@ -89,6 +92,7 @@ contract ArtGobblers is GobblersERC721, LogisticVRGDA, Owned, ERC1155TokenReceiv
     //////////////////////////////////////////////////////////////*/
 
     /// @notice The address of the Goo ERC20 token contract.
+    /// @custom:test-b Another custom tag.
     Goo public immutable goo;
 
     /// @notice The address of the Pages ERC721 token contract.
@@ -344,6 +348,7 @@ contract ArtGobblers is GobblersERC721, LogisticVRGDA, Owned, ERC1155TokenReceiv
     /// limit is enforced during the creation of the merkle proof, which will be shared publicly.
     /// @param proof Merkle proof to verify the sender is mintlisted.
     /// @return gobblerId The id of the gobbler that was claimed.
+    /// @custom:test-c Yet another simple custom tag.
     function claimGobbler(bytes32[] calldata proof) external returns (uint256 gobblerId) {
         // If minting has not yet begun, revert.
         if (mintStart > block.timestamp) revert MintStartPending();

[grandizzy]

that's great, thanks! not a strong opinion but I think would be nicer to have bullet point for them (as Custom key is not relevant for docs) like

Inherits: ....
Authors: ....
An experimental ....
- A first custom tag
- A second custom tag

wdyt?

[zerosnacks]

Thanks!

Supportive of changing the format, my suggestion would be to additionally add a header:

Notes:

- A first custom tag
- A second custom tag

as in a list with a header stating Notes in bold

[leovct]

I also prefer this approach.

[zerosnacks]

Thanks @leovct!

[grandizzy]

Lgtm!

[Metaxona]

okay i just now looked at the output for this one, looks good, but it is missing the label after @custom: making the notes section confusing instead of informative

ex.

this

@custom:some-info Hello

outputs this

Notes:

• Hello

instead of

Notes:

• some-info : Hello

[leovct]

okay i just now looked at the output for this one, looks good, but it is missing the label after @custom: making the notes section confusing instead of informative

ex.

this

@custom:some-info Hello

outputs this

Notes:

• Hello

instead of

Notes:

• some-info : Hello

It should be fixed! :)