solhint

use-natspec

Recommended Badge Category Badge Default Severity Badge warn

The {“extends”: “solhint:recommended”} property in a configuration file enables this rule.

Description

Enforces the presence and correctness of NatSpec tags.

Options

This rule accepts an array of options:

Index Description Default Value
0 Rule severity. Must be one of “error”, “warn”, “off”. warn
1 A JSON object with natspec properties. See EXAMPLE CONFIG section below. Check EXAMPLE CONFIG

Example Config

{
  "rules": {
    "use-natspec": [
      "warn",
      {
        "title": {
          "enabled": true,
          "ignore": {}
        },
        "author": {
          "enabled": true,
          "ignore": {}
        },
        "notice": {
          "enabled": true,
          "ignore": {}
        },
        "param": {
          "enabled": true,
          "ignore": {}
        },
        "return": {
          "enabled": true,
          "ignore": {}
        }
      }
    ]
  }
}

Notes

Examples

👍 Examples of correct code for this rule

Contract with valid NatSpec


                /// @title Token contract
                /// @author Me
                /// @notice This contract handles tokens
                contract Token {
                  /// @notice Transfers tokens
                  /// @param to The recipient address
                  /// @param amount The amount to transfer
                  /// @return success Whether the transfer succeeded
                  function transfer(address to, uint256 amount) public returns (bool success) {
                    return true;
                  }
                }
              

You can disable specific tags globally or by type/name using the ignore option in the config. For example:

{
                "use-natspec": [
                  "warn",
                  {
                    "title": {
                      "enabled": true,
                      "ignore": {
                        "contract": ["MyContract"],
                        "*": ["LegacyContract"]
                      }
                    },
                    "param": { "enabled": false }
                  }
                ]
              }

The default configuration enables all checks with no ignore rules:

{
                "title": { "enabled": true, "ignore": {} },
                "author": { "enabled": true, "ignore": {} },
                "notice": { "enabled": true, "ignore": {} },
                "param": { "enabled": true, "ignore": {} },
                "return": { "enabled": true, "ignore": {} }
              }

👎 Examples of incorrect code for this rule

Missing @notice and incorrect @param and @return tags


                /// @title Token contract
                contract Token {
                  /// @param wrongParam Not matching actual parameter
                  function transfer(address to) public returns (bool) {
                    return true;
                  }
                }
                

Version

This rule was introduced in the latest version.

Resources