[lucy-dev] Grouping of methods in documentation

[Nick Wellnhofer]

Lucifers,

I'm scratching my head over the question of how to best organize the list of 
methods in a class for documentation purposes. I think it's useful to group 
methods by superclasses because methods declared more "recently" in the class 
hierarchy tend to be of more interest to the reader. But I'm not sure whether 
it's better to group "novel" or "fresh" methods together.

In Clownfish parlance, a method is "novel" in a class if it's the first time 
the method is declared in the class hierarchy. Grouping novel methods together 
obviously results in a very nice order. First we show the novel methods of a 
class, then the novel methods of its superclass and so on. The only exception 
are abstract methods. If a class is the first to implement an abstract method, 
this is an important piece of information, so the first implementation of an 
abstract method should be treated like it was novel.

Another approach is to combine "fresh" methods. A method is fresh if it is 
directly implemented in a class, either because it's novel or because it 
overrides a method from a superclass. I think the fact that there's an 
overriding method is not that important to document. But grouping fresh 
methods together results in a layout that closely resembles the .cfh files, so 
it might have some benefits.

I'm leaning towards combining novel methods with an exception for abstract 
methods. What do you think?

Nick