Skip to content

Commenting

  1. For public or external methods and variables, use NatSpec comments.
  • forge doc will parse these to autogenerate documentation.
  • Etherscan will display them in the contract UI.

  1. For simple NatSpec comments, consider just documenting params in the docstring, such as /// @notice Returns the sum of `x` and `y`., instead of using @param tags.

  2. For complex NatSpec comments, consider using a tool like PlantUML to generate ASCII art diagrams to help explain complex aspects of the codebase.

  3. Any markdown in your comments will carry over properly when generating docs with forge doc, so structure comments with markdown when useful.

    • Good: /// @notice Returns the sum of `x` and `y`.
    • Bad: /// @notice Returns the sum of x and y.