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?

  • well your first level of documentation is naming - make sure your events have good names
    – jk.
    Feb 21, 2013 at 12:11
  • 1
    @jk. Of course. The question is not so much documentation for explaining the behavior as it is about documentation for discovery. Even if the events have extremely clear names, if you don't know they are fired, they are of little use.
    – MattiSG
    Feb 21, 2013 at 12:31
  • indeed naming is the first thing not the only thing
    – jk.
    Feb 21, 2013 at 12:32

3 Answers 3


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.

  • “secondary” was not meant in a derogative manner. I called it this way because it is not an interface as per the definition of an API: you don't call events, you listen to them. It is “secondary” as it belongs to a “second category” of interfaces. Whether you consider it primary or secondary in importance completely depends on the library coding style.
    – MattiSG
    Feb 21, 2013 at 12:34
  • @MattiSG we all agree then :) Feb 21, 2013 at 13:38

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.

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.

  • The question was not about documenting who fires events, but what are the events. Plus, I disagree with the definition of code documentation you give (in this particular context): if I am an event listener, I don't give a damn about why am I here beyond the fact that the event source decided it was relevant. The only context I am in is the one that is passed to me. I don't want to know which methods fire which events, I want to know what methods do, and what events are available to me. When and how both are related is not my problem, it's the source's one.
    – MattiSG
    Feb 21, 2013 at 12:37

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.