How do you generate the NatSpec documentation?

Greetings, I hope I chose the best topic for this question.

I'm curious what tools do you use to generate the NatSpec documentation and curious on what some of those keywords mean.
Looking at ERC1155.sol:

    /**
     * @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {_mint}.
     *
     * Emits a {TransferBatch} event.
     *
     * Requirements:
     *
     * - `ids` and `amounts` must have the same length.
     * - If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155BatchReceived} and return the
     * acceptance magic value.
     */

Could you please explain how this @dev commentary is formed?
Not clear to me what's ROOT:erc1155.adoc etc. I would like to pick it up too if it makes docs clearer!
Thanks!

1 Like

We use solidity-docgen to generate a static documentation site from the NatSpec in the code, we also prepare .adoc files to put all the documentation. When you see xref:ROOT:erc1155.adoc is just referencing to which documentation the word inside [] links to.

You can see the documentation display normally: in the docs page, and Batched is a link that points to erc1155.adoc#batch-operations

1 Like

This is the tool that we use: https://github.com/OpenZeppelin/solidity-docgen