Natspec，NaturalLanguageSpecification，是使用自然语言注释向Solidity代码添加文档的标准格式。Natspec注释使Solidity代码更具有可读性和理解性。
简介
Natspec注释使Solidity代码更具有可读性和理解性。Natspec，Natural Language Specification，是使用自然语言注释向 Solidity 代码添加文档的标准格式。Natspec提供了一个易于阅读的描述，说明函数或合约的作用，有哪些参数，返回什么值，以及其它相关的信息。
许多开发工具（例如 Solidity 编译器和 Remix 等 IDE）可以解析 natspec 注释并生成人类可读的文档。
<br>
示例
// 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>
生成文档
使用OpenZeppelin的docgen工具，可以生成markdown格式的文档文件。可自行了解~
<br>
区块链\&web3开发技术交流群（纯净版）欢迎加入交流:<https://t.me/+PGwDonY3f2o3NDg1>
