OpenZeppelin
Documentation of events emitted by functions
Currently, we require the natspec comment of each function to include details of events emitted by this function.
Some cases are however not that simple and need to be clarified:
- Should a function's documentation include events emitted by sub-calls?
- What if a function may or may not emit an event depending on the state? What wording should be used?
- What if a function triggers another contract to emit an event?
As an example, the PullPayment includes a dedicated Escrow instance. Calling withdrawPayments on the pull payment contract will not directly emit any events, but will cause the Escrow (which is another address) to emit the Withdrawn event. Should that be documented in the withdrawPayments natspec comments?
A proposal is to automate that part in the future, by analysing the function code and detecting events being emitted, but that might be difficult to do, particularly with regard to "WILL" vs "MAY"
An argument for automating it in doc generation is that if you are looking at the code it's already more or less evident what events are emitted because you can see them there. If they are indirectly emitted as part of a function call it's not so obvious but still possible to get the info, and with go-to-definition becoming more available even more so.
As for "will emit" vs "may emit", I think it would be fine to default to "may emit".
