Solidity | Natspec注释格式

  • 卡卡
  • 更新于 5天前
  • 阅读 214

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>

点赞 0
收藏 0
分享
本文参与登链社区写作激励计划 ,好文好收益,欢迎正在阅读的你也加入。

0 条评论

请先 登录 后评论
卡卡
卡卡
智能合约开发&安全,去中心化爱好者