Re: continuing documentation

[Gordon Matzigkeit]

>>>>> OKUJI Yoshinori writes:

 >> Tagging comments is not acceptable to me, because I feel that we
 >> have enough information already to make a comparison of text.  We
 >> know how to collapse simple Texinfo into text, the word order is
 >> easy to compare, and with some heuristics, we can generate a first
 >> guess at the Texinfo when we only have the C comment.

 OY> For now, I'm afraid of two things about that. One of these is
 OY> that people often write documents and comments differently, of
 OY> course, intentionally. Comments tend to be terse, because too
 OY> long statements are annoying for programmers, while documents
 OY> tend to be verbose, to introduce concepts by making sentenses
 OY> easier to understand.

I don't think that is too much of a problem for the Hurd documentation
style, but you are right that it would be for different projects.  So,
perhaps it is best to leave copying the documentation back into
comments as an option.

 OY> The other is that, in source code, one or more comments are
 OY> usually attached to each prototype, but, in documentation,
 OY> multiple function definitions (and their descriptions) are
 OY> sometimes collected into one paragraph for clarity (e.g. by using
 OY> @deftypefunx).

I don't think this is insurmountable.  We could simply avoid the text
comparison for such functions, assuming that their text will be
completely different from the source.  For some functions, we can
still do the right thing, because the comment style is:

/* SHARED-COMMENT */
PROTOTYPE-1;
PROTOTYPE-2;

and that becomes:

@deftypefun PROTOTYPE-1
@deftypefunx PROTOTYPE-1
SHARED-COMMENT
@end deftypefun

 OY> Both of them would increase "false positive", that is, the number
 OY> of items at which you don't need to take a look.

Agreed.  I think the only thing that makes us still win is the fact
that Hurd sources follow pretty clear conventions, which we can rely
on to give more information than typical free-form code.  We don't
need to make something completely generic, only something that is
useful for this project and others similar to it.

 OY> Anyway, I'm going to start hacking with easy things (parsing C
 OY> and Texinfo, and detecting functions which is absent in C or
 OY> Texinfo).

Cool.  I look forward to seeing what you have, so I can start working,
too. :)

-- 
 Gordon Matzigkeit <gord@fig.org>  //\ I'm a FIG (http://fig.org/)
Committed to freedom and diversity \//  Run Bash (http://fig.org/gnu/bash/)