[Top][All Lists]

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

Re: list, set, oset, map, omap: avoid imperative voice in documentation

From: Bruno Haible
Subject: Re: list, set, oset, map, omap: avoid imperative voice in documentation
Date: Sun, 09 Feb 2020 00:54:32 +0100
User-agent: KMail/5.1.3 (Linux/4.4.0-171-generic; KDE/5.18.0; x86_64; ; )

Paul Eggert wrote:
> Plus, it's odd to use one style before a "{" and a different style after.

I think it's useful to make this emphasis - in order to write a function
specification that can be understood without reading the function body.

When I write code, I'm of course a bit annoyed to make the difference
between the specification (in the .h file) and the implementation (in the
.c file). But this annoyance is rewarded with a 10 times higher value:
the ability to read the specification without looking into the implementation
(which is often 3 to 20 times larger than the specification).

> perhaps "'clearerr (STREAM)' clears the 
> error indicator for STREAM." which is in reverse order of what the text 
> says

That's only because we are writing the specification before the declaration,
and directly looking at the .h file. If you were reading Doxygen generated
HTML [1], it would present the declaration first and the specification
immediately following it.

> the "Clears" of the comment disagrees with the "clear" of the function name.

Yes, function names use the imperative, like C does: we write
   goto label;           NOT       goesto label;
   return x;             NOT       returns x;
- because inside the function's body the imperative aspects are predominant.


[1] http://xerces.apache.org/xerces-c/apiDocs-3/classBase64.html

reply via email to

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