feat(doc): infer hyperlinks for {Contract}, {function}, and {Contract-function} references

[PaulRBerg]

Component

Forge

Describe the feature you would like

It is a fairly common strategy to refer to other functions and contracts by using {} brackets in NatSpec comments. OpenZeppelin does this, for instance:

• https://github.com/OpenZeppelin/openzeppelin-contracts/blob/f8e3c375d19bd12f54222109dd0801c0e0b60dd2/contracts/token/ERC721/ERC721.sol#L60
• https://github.com/OpenZeppelin/openzeppelin-contracts/blob/f8e3c375d19bd12f54222109dd0801c0e0b60dd2/contracts/token/ERC721/ERC721.sol#L178
• https://github.com/OpenZeppelin/openzeppelin-contracts/blob/f8e3c375d19bd12f54222109dd0801c0e0b60dd2/contracts/token/ERC721/ERC721.sol#L232

I imagine that the algorithm would go something like this in Forge:

• {Contract}: link to the contract page, e.g. /src/Contract.sol/contract.Contract.md
• {function} (or {event}}: relative link in the same document with #, e.g. #-function
• {Contract-function}: link to the contract page and the function section by adding a # in the URL, e.g. /src/Contract.sol/contract.Contract.md#function

[mds1]

I wonder why OZ does {Contract-function}, I feel like {Contract.function} is more common? Either way don't feel strongly, and supportive of this feature request 👍

cc @rkrasiuk

[PaulRBerg]

Not sure why OZ decided to go with that format, but I like it. I wouldn't use dot notation in NatSpec comments since I'd prefer to separate actual syntax from documentation references.

[benbcjdev]

I know it's been a while but I want to add support for this feature, would love to be able to automatically hyperlink to other methods/contracts in the docs.