How to document events?

Question

Code documentation is usually related to a piece of code, be it small (method-level) or larger (class- or namespace-level). However, it is always about the inputs and the outputs of that piece of code, possibly describing its behavior and caveats.

It doesn't make much sense to document events fired by a class in the methods that may fire them: they may be duplicated and, by the definition of events, the listener is not expected to care about what triggers them, only handling them.

Documenting all events at the top of a class seems quite heavy, as someone willing to get an overview of the class behavior might not be so interested at deep diving at this “secondary interface”.

This problem is mitigated in strongly-typed languages such as Java (yes, unless you use anonymous classes, but it doesn't seem so common), as the events will be defined in their own classes, which can then be documented.

But, in languages with looser types, where an event is simply a String identifier and a series of parameters, it is much more difficult to find the proper place for documenting these id/params combinations.

So: where should fired events be documented in languages that don't model them explicitly?

Answer 1

It belongs in side documentation, which is usually called a reference. Such documentation, as you outlined it, doesn't belong to the class/method documentation, so the best place is to have dedicated documentation for them.

For exemple, take a look at how Symfony2 documents its exposed internal events: http://symfony.com/doc/current/reference/events.html

Don't be too quick to dismiss events as "secondary interface". They usually are quite the opposite, as they are the main way to extend functionnality in a really loosely coupled way.

Answer 2

First, events are not secondary interface. They fully belong to the interface.

I document them in three parts:

• at the sender's side: list of events that can be raised.
• at the receiver's side: list of events that can trigger an action.
• at a specific module where all events are declared: full description of each event.

Answer 3

Every method should document it's gazintas and gazoutas. The things that go into a method include its parameters, and relevant states of the object it belongs to. The things that go out of it include its return value, relevant changes in the object's state, events it fires, changes to persistent data, etc. One key point of code documentation is to answer the "Who am I? Why am I here?" questions. If you have to read the code to learn those answers, the documentation is insufficient.