La documentazione del codice è in genere correlata a un pezzo di codice, sia esso piccolo (metodo-livello) o più grande (classe o livello di spazio dei nomi). Tuttavia, si tratta sempre degli input e degli output di quel pezzo di codice, possibilmente descrivendo il suo comportamento e i caveat.
Non ha molto senso documentare gli eventi lanciati da una classe nei metodi che possono attivarli: possono essere duplicati e, dalla definizione di eventi, non ci si aspetta che l'ascoltatore si preoccupi di cosa li innesca, solo gestendoli.
Documentare tutti gli eventi nella parte superiore di una classe sembra abbastanza pesante, in quanto qualcuno disposto a ottenere una panoramica del comportamento di classe potrebbe non essere così interessato alle immersioni profonde a questa "interfaccia secondaria".
Questo problema è attenuato in linguaggi strongmente tipizzati come Java (sì, a meno che non si utilizzino classi anonime, ma non sembra così comune), poiché gli eventi saranno definiti nelle proprie classi, che possono quindi essere documentati .
Tuttavia, nelle lingue con tipi più sciolti, in cui un evento è semplicemente un identificatore di stringa e una serie di parametri, è molto più difficile trovare il posto giusto per documentare queste combinazioni id / param.
Quindi: dove dovrebbero essere documentati gli eventi licenziati in lingue che non li modellano esplicitamente?