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

[Bruno Haible]

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;
and
   return x;             NOT       returns x;
- because inside the function's body the imperative aspects are predominant.

Bruno

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