bug-hurd
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: continuing documentation


From: OKUJI Yoshinori
Subject: Re: continuing documentation
Date: Sat, 23 Jun 2001 13:15:58 +0900

From: Gordon Matzigkeit <gord@fig.org>
Subject: Re: continuing documentation
Date: 22 Jun 2001 19:16:02 -0600

> 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.

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

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

Both of them would increase "false positive", that is, the number of
items at which you don't need to take a look. If the number is
too big, the tool would be just useless, because it would be much
faster to read through header files and documents by your own eyes.

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

Okuji



reply via email to

[Prev in Thread] Current Thread [Next in Thread]