NATSpec格式

Solidity契约可以使用特殊形式的注释为函数、返回变量等提供丰富的文档。这种特殊形式被命名为以太坊自然语言规范格式（natspec）。

注解

NatSpec的灵感来自于 Doxygen 。虽然它使用Doxy样式的注释和标记，但并不打算与Doxym保持严格的兼容性。请仔细检查下面列出的支持的标签。

此文档分为以开发人员为中心的消息和面向最终用户的消息。这些消息可以在最终用户（人）将与合同交互时（即签署交易）显示给他们。

建议对所有公共接口（ABI中的所有内容）使用natspec对solidity契约进行完全注释。

natspec包含智能合约作者将使用的注释的格式，并由solidity编译器理解这些注释。下面还详细介绍了solidity编译器的输出，它将这些注释提取为机器可读的格式。

NatSpec还可能包括第三方工具使用的注释。这些很可能是通过 @custom:<name> 标记，一个很好的用例是分析和验证工具。

文档示例

文档插入在每个 contract ， interface ， function ，以及 event 使用DOOXO记数法格式。一个 public 状态变量等效于 function 为了NatSpec的目的。

为了坚固，你可以选择 /// 对于单行或多行注释，或 /** 结束于 */ .
对于Vyper，使用 """ indented to the inner contents with bare comments. See the Vyper documentation 。

下面的示例显示使用所有可用标记的契约和函数。

注解

solidity编译器仅解释外部或公共标记。欢迎对内部和私有函数使用类似的注释，但这些注释将不会被解析。

这在未来可能会改变。

open in Remix

// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.2 < 0.9.0;

/// @title A simulator for trees
/// @author Larry A. Gardner
/// @notice You can use this contract for only the most basic simulation
/// @dev All function calls are currently implemented without side effects
/// @custom:experimental This is an experimental contract.
contract Tree {
    /// @notice Calculate tree age in years, rounded up, for live trees
    /// @dev The Alexandr N. Tetearing algorithm could increase precision
    /// @param rings The number of rings from dendrochronological sample
    /// @return Age in years, rounded up for partial years
    function age(uint256 rings) external virtual pure returns (uint256) {
        return rings + 1;
    }

    /// @notice Returns the amount of leaves the tree has.
    /// @dev Returns only a fixed number.
    function leaves() external virtual pure returns(uint256) {
        return 2;
    }
}

contract Plant {
    function leaves() external virtual pure returns(uint256) {
        return 3;
    }
}

contract KumquatTree is Tree, Plant {
    function age(uint256 rings) external override pure returns (uint256) {
        return rings + 2;
    }

    /// Return the amount of leaves that this specific kind of tree has
    /// @inheritdoc Tree
    function leaves() external override(Tree, Plant) pure returns(uint256) {
        return 3;
    }
}

标签

所有标签都是可选的。下表说明了每个natspec标签的用途和使用位置。作为一种特殊情况，如果不使用标记，那么solidity编译器将解释 /// 或 /** 以同样的方式发表评论 @notice .

标签		语境
`@title`	描述合同/接口的标题	合同、库、接口
`@author`	作者姓名	合同、库、接口
`@notice`	向最终用户解释它的作用	约定、库、接口、函数、公共状态变量、事件
`@dev`	向开发人员解释任何额外的细节	约定、库、接口、函数、状态变量、事件
`@param`	记录参数，就像在DOOXO中一样(后面必须跟参数名称)	功能、事件
`@return`	记录契约函数的返回变量	函数，公共状态变量
`@inheritdoc`	从基函数复制所有缺少的标记（后面必须跟合同名称）	函数，公共状态变量
`@custom:...`	自定义标记，语义是应用程序定义的	到处都是

如果函数返回多个值，例如 (int quotient, int remainder) 然后使用多个 @return 语句的格式与 @param 声明。

自定义标记以 @custom: 并且后面必须跟一个或多个小写字母或连字符。但是，它不能以连字符开头。它们可以在任何地方使用，并且是开发人员文档的一部分。

动态表达式

solidity编译器将把natspec文档从solidity源代码传递到JSON输出，如本指南所述。这个JSON输出的使用者，例如终端用户客户机软件，可以直接向终端用户展示它，或者它可以应用一些预处理。

例如，一些客户端软件将呈现：

open in Remix

/// @notice This function will multiply `a` by 7

致最终用户：

This function will multiply 10 by 7

如果一个函数正在被调用并且输入 a 分配的值为10。

指定这些动态表达式超出了solidity文档的范围，您可以在 the radspec project .

继承说明

没有NatSpec的函数将自动继承其基函数的文档。例外情况包括：

当参数名称不同时。
当有多个基函数时。
当有一个明确的 @inheritdoc 标记，指定应使用哪个协定来继承。

文件输出

当编译器解析时，上面例子中的文档将生成两个不同的JSON文件。一个是在执行函数时由最终用户作为通知使用，另一个是由开发人员使用。

如果上述合同另存为 ex1.sol 然后，您可以使用以下方法生成文档：

open in Remix

solc --userdoc --devdoc ex1.sol

产量在下面。

注解

从Solidity版本0.6.11开始，NatSpec输出还包含 version 和一个 kind 田野。目前， version 设置为 1 和 kind 一定是其中之一 user 或 dev 。将来可能会引入新版本，而不建议使用旧版本。

用户文档

上述文档将生成以下用户文档JSON文件作为输出：

open in Remix

{
  "version" : 1,
  "kind" : "user",
  "methods" :
  {
    "age(uint256)" :
    {
      "notice" : "Calculate tree age in years, rounded up, for live trees"
    }
  },
  "notice" : "You can use this contract for only the most basic simulation"
}

注意，查找方法的关键是函数的规范签名，如 Contract ABI 而不仅仅是函数名。

开发人员文档

除了用户文档文件之外，还应该生成一个开发人员文档JSON文件，其外观如下：

open in Remix

{
  "version" : 1,
  "kind" : "dev",
  "author" : "Larry A. Gardner",
  "details" : "All function calls are currently implemented without side effects",
  "custom:experimental" : "This is an experimental contract.",
  "methods" :
  {
    "age(uint256)" :
    {
      "details" : "The Alexandr N. Tetearing algorithm could increase precision",
      "params" :
      {
        "rings" : "The number of rings from dendrochronological sample"
      },
      "return" : "age in years, rounded up for partial years"
    }
  },
  "title" : "A simulator for trees"
}