[Top][All Lists]

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

Re: continuing documentation

From: Thomas Bushnell, BSG
Subject: Re: continuing documentation
Date: 29 Jun 2001 11:04:00 -0700
User-agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7

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.

reply via email to

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