Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
well your first level of documentation is naming - make sure your events have good names –  jk. Feb 21 '13 at 12:11
    
@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 '13 at 12:31
    
indeed naming is the first thing not the only thing –  jk. Feb 21 '13 at 12:32

3 Answers 3

up vote 2 down vote accepted

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/2.0/book/internals.html#events

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.

share|improve this answer
    
“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 '13 at 12:34
    
@MattiSG we all agree then :) –  Clement Herreman Feb 21 '13 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.
share|improve this answer

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.

share|improve this answer
    
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 '13 at 12:37

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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