Room for improvement in contracts documentation
eztierney opened this issue · comments
The Centre Token minting contracts are in general well documented, and the documentation adheres to the NatSpec format. There is, however, room for improvement. First, MasterMinter.sol has no documentation at all. Second, while all contracts have a short description of each function, all comments make use of only the @dev tag among the many available in NatSpec.
Yet another instance where documentation can be improved is the following comment in Controller.sol: “set the controller of a particular _worker”. This might lead the user to think that each worker has a single controller, while the system in fact allows it to have more than one.
Finally, the comment “allows control of configure/remove minter…” in MintController seems to refer to the configureMinter and removeMinter functions, but these are not referenced using their full names.
Consider adding complete docstrings for all contracts, struct fields, state variables, mapping keys and functions, and having comments more clearly and faithfully represent the functionality of the contracts.
