## 0x00：简介

Natspec注释使Solidity代码更具有可读性和理解性。Natspec，Natural Language Specification，是使用自然语言注释向 Solidity 代码添加文档的标准格式。Natspec提供了一个易于阅读的描述，说明函数或合约的作用，有哪些参数，返回什么值，以及其它相关的信息。

许多开发工具（例如 Solidity 编译器和 Remix 等 IDE）可以解析 natspec 注释并生成人类可读的文档。

> 参考：https://jamesbachini.com/natspec-in-solidity/

<br>

## 0x01：示例

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

/**
 * @title Natspec
 * @author kaka
 * @dev An example contract to demonstrate natspec documentation
 * @notice This contract is untested
 * @custom:experimental This is an experimental contract.
 */
contract Natspec {
    string public txt = "I like code comments";

    /**
     * @dev Update the txt state variable
     * @notice This returns a uint for no reason
     * @param {string} _txt a new text string
     * @return {uint} just a demo number
     */
    function update(string memory _txt) public returns (uint) {
        txt = _txt;
        return 1;
    }
}

- `@title`：该标签指定合约名；
- `@notice`：该标签用于描述函数或合约的功能；
- `@dev`：该标签用于提供与开发相关的附加信息。例如，可以使用此标签来提供有关某个函数如何工作的详细信息，或者提醒自己在部署到生产环境之前删除某行代码；
- `@param`：该标签用于描述函数的输入参数。每个参数都应该包含此标签，并对该参数进行简短描述；
- `@return`：该标签用于描述函数的返回值。应该为每个返回值包含此标记，并对该返回值进行简短描述；
- `@devnote`：该标签与`@dev`类似，但它用于提供特定于开发人员的注释。例如，您可以使用此标签来提醒自己将来重构某段代码;
- `@inheritdoc`：该标签用于指示函数或合约从父合约继承其文档。如果您有一个从父合约继承的函数并且您不想重复文档，那么这非常有用。
- `@custom`：该标签用于定义不属于标准 natspec 标签的自定义标签。如果您想创建特定于您的项目的自己的文档标签，这非常有用；

<br>

## 0x02: 生成文档：

使用OpenZeppelin的docgen工具，可以生成markdown格式的文档文件。可自行了解~