use-natspec

March 5, 2026 · View on GitHub

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

For internal or private function this rule checks natspec as configured, only if there are tags present. If not, function is skipped.
For external or public function this rule checks natspec as specified in the config.
If a function or return value has unnamed parameters (e.g. function foo(uint256, uint256 _amount)), the rule DOES not check ANY of the params/return tags
If a function or variable has @inheritdoc, the rule skips the validation.
The rule supports both /// and /** */ style NatSpec comments.
If a custom config is provided, it is merged with the default config. Only the overridden fields need to be specified.

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 Solhint 6.0.0