[lucy-dev] Grouping of methods in documentation

[Nick Wellnhofer <we...@aevum.de>]

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

Re: [lucy-dev] Grouping of methods in documentation

[Marvin Humphrey <ma...@rectangular.com>]

On Thu, Dec 4, 2014 at 2:18 PM, Nick Wellnhofer <we...@aevum.de> wrote:

> For the C bindings, it's important to include at least the declarations for
> inherited methods because they're different in a subclass than in a
> superclass. Suppose you want to set the boost on a TermQuery. If the
> TermQuery documentation links to Query for SetBoost, you'll find:
>
>     void
>     LUCY_Query_Set_Boost(
>         lucy_Query* self,
>         float boost
>     );
>
> So a novice will probably end up writing
>
>    Query_Set_Boost((Query*)term_query, boost);
>
> instead of
>
>     TermQuery_Set_Boost(term_query, boost);

Excellent point.

Marvin Humphrey

Re: [lucy-dev] Grouping of methods in documentation

[Nick Wellnhofer <we...@aevum.de>]

On 03/12/2014 02:59, Marvin Humphrey wrote:
> Well, I don't think our disagreement is that serious.  I meant a link for each
> method, not a link for each ancestor class -- so it's not that I'm opposed to
> having inherited methods shown at all.  (Thinking a little harder, my
> preference would be to follow the conventions of the host language community.)

I'm only talking about the C documentation. I agree that other for host 
languages, we should follow the community conventions.

For the C bindings, it's important to include at least the declarations for 
inherited methods because they're different in a subclass than in a 
superclass. Suppose you want to set the boost on a TermQuery. If the TermQuery 
documentation links to Query for SetBoost, you'll find:

     void
     LUCY_Query_Set_Boost(
         lucy_Query* self,
         float boost
     );

So a novice will probably end up writing

    Query_Set_Boost((Query*)term_query, boost);

instead of

     TermQuery_Set_Boost(term_query, boost);

(The example pages I uploaded are not correct in this regard, but this is 
already fixed in the markdown_v2 branch).

If we include the method declarations for all inherited methods, I can't see 
how it would hurt to include the full method documentation as well.

Nick

Re: [lucy-dev] Grouping of methods in documentation

[Peter Karman <pe...@peknet.com>]

Marvin Humphrey wrote on 12/2/14, 5:59 PM:
> On Tue, Dec 2, 2014 at 3:43 PM, Nick Wellnhofer<we...@aevum.de>  wrote:
>> On 02/12/2014 23:08, Marvin Humphrey wrote:
>>>
>>> I'd suggest including complete documentation only when a DocuComment
>>> appears in the .cfh source file.  For subroutines, that will generally mean
>>> only novel methods and inert functions, but it's conceievable that an
>>> inherited method could provide a DocuComment explaining something about its
>>> implementation.
>>>
>>> For public methods whose interfaces are established in superclasses, I
>>> suggest linking only.
>>
>> I disagree. Especially for casual users, I think it's helpful to show all
>> the methods that a class implements. Otherwise, you miss many methods or you
>> end up permanently switching between the documentation of the class and one
>> or two of its superclasses. I'd only make an exception for Clownfish::Obj.
>
> Well, I don't think our disagreement is that serious.  I meant a link for each
> method, not a link for each ancestor class -- so it's not that I'm opposed to
> having inherited methods shown at all.  (Thinking a little harder, my
> preference would be to follow the conventions of the host language community.)
>

I like the idea of method docs (links at minimum) in every subclass 
documentation. One of things about my own documentation that I dislike is having 
to reference multiple pieces of documentation in order to get a complete sense 
of the API for a given class. If that consolidation were automated, it would be 
great for users, imo.


-- 
Peter Karman  .  http://peknet.com/  .  peter@peknet.com

Re: [lucy-dev] Grouping of methods in documentation

[Marvin Humphrey <ma...@rectangular.com>]

On Tue, Dec 2, 2014 at 3:43 PM, Nick Wellnhofer <we...@aevum.de> wrote:
> On 02/12/2014 23:08, Marvin Humphrey wrote:
>>
>> I'd suggest including complete documentation only when a DocuComment
>> appears in the .cfh source file.  For subroutines, that will generally mean
>> only novel methods and inert functions, but it's conceievable that an
>> inherited method could provide a DocuComment explaining something about its
>> implementation.
>>
>> For public methods whose interfaces are established in superclasses, I
>> suggest linking only.
>
> I disagree. Especially for casual users, I think it's helpful to show all
> the methods that a class implements. Otherwise, you miss many methods or you
> end up permanently switching between the documentation of the class and one
> or two of its superclasses. I'd only make an exception for Clownfish::Obj.

Well, I don't think our disagreement is that serious.  I meant a link for each
method, not a link for each ancestor class -- so it's not that I'm opposed to
having inherited methods shown at all.  (Thinking a little harder, my
preference would be to follow the conventions of the host language community.)

In any case, if you feel strongly about the issue, let's go with your plan.

Marvin Humphrey

Re: [lucy-dev] Grouping of methods in documentation

[Nick Wellnhofer <we...@aevum.de>]

On 02/12/2014 23:08, Marvin Humphrey wrote:
> I'd suggest including complete documentation only when a DocuComment
> appears in the .cfh source file.  For subroutines, that will generally mean
> only novel methods and inert functions, but it's conceievable that an
> inherited method could provide a DocuComment explaining something about its
> implementation.
>
> For public methods whose interfaces are established in superclasses, I suggest
> linking only.

I disagree. Especially for casual users, I think it's helpful to show all the 
methods that a class implements. Otherwise, you miss many methods or you end 
up permanently switching between the documentation of the class and one or two 
of its superclasses. I'd only make an exception for Clownfish::Obj.

Nick

Re: [lucy-dev] Grouping of methods in documentation

[Marvin Humphrey <ma...@rectangular.com>]

On Tue, Dec 2, 2014 at 1:03 PM, Nick Wellnhofer <we...@aevum.de> wrote:

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

I think the difficulty of reasoning about how to document complex class
hierarchies illustrates why many people consider implementation inheritance
problematic.  :D

More practically...

I'd suggest including complete documentation only when a DocuComment
appears in the .cfh source file.  For subroutines, that will generally mean
only novel methods and inert functions, but it's conceievable that an
inherited method could provide a DocuComment explaining something about its
implementation.

For public methods whose interfaces are established in superclasses, I suggest
linking only.

Marvin Humphrey