Skip to content

Allow @param NatSpec comments for struct and enum #14699

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
BeamNawapat opened this issue Nov 24, 2023 · 1 comment
Closed

Allow @param NatSpec comments for struct and enum #14699

BeamNawapat opened this issue Nov 24, 2023 · 1 comment
Labels

Comments

@BeamNawapat
Copy link

interface IPolicy {
	/**
	 * @dev An enumeration representing the status of a policy.
	 * @param Active The policy is active.
	 * @param Cancelled The policy is cancelled.
	 * @param Expired The policy is expired.
	 */
	enum PolicyStatus {
		Active,
		Cancelled,
		Expired
	}

	/**
	 * @dev A struct representing the data associated with a policy.
	 * @param policyholder The address of the policy holder.
	 * @param status The status of the policy.
	 */
	struct Policy {
		address policyholder;
		PolicyStatus status;
	}
}

I would like to propose an extension of NatSpec support to include the '@param' tag for struct and enum elements. This enhancement would provide more comprehensive documentation capabilities for these essential components, allowing developers to articulate detailed information about the purpose and usage of each parameter within a struct or enum.

Ref: #14267

@nikola-matic
Copy link
Collaborator

Closing this as a partial duplicate of #12295.

We recently added the ability to document struct definitions (without @param, since it's not one) in 0.8.20, and currently have an open PR that would allow you to document individual enum values (again without @param, but it's still along the lines of what you're looking for) - see #14193 (scroll down toward the end of the changed files to see the tests, and thus example usage).

Otherwise, we have no further plans on working on natspec.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants