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
