文档举例

Documentation is inserted above each contract, interface , library, function, and event using the Doxygen notation format.

A public state variable is equivalent to a function for the purposes of NatSpec.

• For Solidity you may choose /// for single or multi-line comments, or /** and ending with */.
• For Vyper, use """ indented to the inner contents with bare comments. See the Vyper documentation.

The following example shows a contract and a function using all available tags.

 // 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 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;
      }
}

标签Tags

All tags are optional. The following table explains the purpose of each NatSpec tag and where it may be used. As a special case, if no tags are used then the Solidity compiler will interpret a /// or /** comment in the same way as if it were tagged with @notice.

If your function returns multiple values, like (int quotient, int remainder) then use multiple @return statements in the same format as the @param statements.

Custom tags start with @custom: and must be followed by one or more lowercase letters or hyphens. It cannot start with a hyphen however. They can be used everywhere and are part of the developer documentation.

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

This function will multiply 10 by 7

文档输出

When parsed by the compiler, documentation such as the one from the above example will produce two different JSON files. One is meant to be consumed by the end user as a notice when a function is executed and the other to be used by the developer.

If the above contract is saved as ex1.sol then you can generate the documentation using:

solc --userdoc --devdoc ex1.sol

And the output is below.

{
  "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"
}

{
  "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"
}