Re: continuing documentation

[Thomas Bushnell, BSG]

OKUJI Yoshinori <okuji@kuicr.kyoto-u.ac.jp> writes:

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

I agree with Okuji here.  The job of the comment in a header file is
to remind a programmer what the interface is.  The job of the manual
is to explain the interface.  We should in general expect that
different text will be used for those two different jobs.