foundry-rs/forge-std

docs: enhance documentation with NatSpec for all public functions

Open

#653 opened on Feb 4, 2025

View on GitHub
 (1 comment) (1 reaction) (0 assignees)Solidity (1,041 stars) (499 forks)user submission
documentationhelp wanted

Description

Related: https://github.com/foundry-rs/book/issues/1303

To do:

Goals:

  • Document all public facing functions with @notice
  • Mark private variables and functions with underscore prefix https://github.com/foundry-rs/forge-std/pull/861
  • Unify layouts to follow common best practices of grouping storage variables
  • Move internal functions up, private functions down
  • Should not modify any user facing function or interface

This will make it easier to autogenerate documentation that we can then load into https://book.getfoundry.sh/reference/forge-std/ and keep it up to date

Contributor guide

Tech stack
None
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Basic Solidity knowledgeFamiliarity with NatSpec commentsUnderstanding of forge std project structure
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
85
Research direction
The issue requires adding NatSpec documentation (specifically @notice tags) to all public functions in the remaining files listed in the checklist: Base.sol, console.sol, console2.sol, safeconsole.sol, Script.sol, StdError.sol, StdMath.sol, StdUtils.sol, Test.sol, Vm.sol. Follow the conventions already established in completed files like StdAssertions.sol and the linked PRs (e.g., #860, #861). Ensure private variables and functions are prefixed with underscore. Do not modify any user facing function or interface. The goal is to enable autogenerated documentation for the Foundry book.
docs: enhance documentation with NatSpec for all public functions · foundry-rs/forge-std#653 | Good First Issue