注释

代码注释

Solidity 的注释与大括号语言一样：

• 单行注释使用双斜杠： // 注释内容
• 多行注释使用： /* 注释内容 */

NatSpec 注释

Solidity 支持类似 Doxygen 的风格，对合约、函数等对象添加说明性注释。对于使用过 JavaDoc/JSDOC 的开发人员会对这种注释方式比较熟悉。

这种注释的用法如下：

• 单行注释使用三斜杠：///
• 多行注释使用：/** */

下面是一个合约与函数的例子：

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

/// @title 合约标题
/// @author 合约作者
/// @notice 为终端用户解释合约作用
/// @dev 为开发人员提供额外的细节
contract Tank {
    /// @notice 为终端用户解释函数功能
    /// @dev 为开发人员提供额外的细节
    /// @param value 解释参数意义，此处为用户需要的以太币数量
    /// @return 返回值类型以及代表的意义，如 true 表示操作成功
    function faucet(uint value) public returns (bool) {
        require(value <= address(this).balance, unicode"以太币余额不足");
        payable(msg.sender).transfer(value);
        return true;
    }

    receive() external payable {}
}

这种风格规范称为 NatSpec（Ethereum Natural Language Specification Format，以太坊自然语言规范格式）。

NatSpec 注释有两种使用：

• 生成用户文档
• 生成开发者文档

另外，在用户发起交易时，有些客户端工具可能会使用 NatSpec 注释向用户提供说明。甚至有些客户端能根据 NatSpec 动态渲染用户说明：

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

contract Tank {
    /// @notice 水龙头，提供 `value` 个以太币用于测试
    function faucet(uint value) public {
        payable(msg.sender).transfer(value);
    }
}

当用户提供 value=1 时，客户端动态渲染为：水龙头，提供 1 个以太币用于测试。

以上面的 NatSpec.sol 为例，使用 solc --userdoc ./NatSpec.sol 可以生成面向用户的JSON格式文档，使用 solc --devdoc ./NatSpec.sol 可以生成面向开发者的JSON格式文档：

> solc --userdoc --devdoc ./NatSpec.sol
======= NatSpec.sol:Tank =======
Developer Documentation
{
	"author": "合约作者",
	"details": "为开发人员提供额外的细节",
	"kind": "dev",
	"methods": {
		"faucet(uint256)": {
			"details": "为开发人员提供额外的细节",
			"params": {
				"value": "解释参数意义，此处为用户需要的以太币数量"
			},
			"returns": {
				"_0": "返回值类型以及代表的意义，如 true 表示操作成功"
			}
		}
	},
	"title": "合约标题",
	"version": 1
}
User Documentation
{
	"kind": "user",
	"methods": {
		"faucet(uint256)": {
			"notice": "为终端用户解释函数功能"
		}
	},
	"notice": "为终端用户解释合约作用",
	"version": 1
}