natSpec comments for contracts and functions
addresses task #3 (closed) of fathom/org#82 (closed)
For functions: I chose to use the
-
@notice
tag to display general information about how to use the function if it was expected to be called by a user. (@notice is to be displayed to the end user -
@dev if the function was not userdirected (internal, access-limited,...) AND/OR to mention sideEffects (sending tokens, advancing assessment) or implicit assumptions (e.g. assuming a certain number of availableMembers in the concept)
For contracts:
- @notice explains the purpose of the contract
- @dev implementation specific notes (e.g. mentioning proxyContract architecture)
state declarations
I am being explicit here (see. Assessment.sol)
Edited by dju