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

[Paul Eggert]

I'm with Jim. The imperative style is shorter, matches the style of the 
imperative programming language we're using, and is more grammatical in 
the sense that "Free an iterator." is an English sentence whereas "Frees 
an iterator." is not.

Plus, it's odd to use one style before a "{" and a different style after.

> The real difference is: Am I talking to a user of the function? Or am
> I explaining the implementation details of the function?

When talking to a function's user, it's fine for the comment to stand 
for a call to the function. For example:

/* Clear the error indicator for STREAM.  */
void clearerr (FILE *__stream);

This comment is saying "'Clear the error indicator for STREAM' = 
'clearerr (STREAM)'." In contrast, if we change the comment's "Clear" to 
"Clears" then the comment is saying something like "'Clears the error 
indicator for STREAM' is something that 'clearerr (STREAM)' does." which 
is indirect and awkward, or perhaps "'clearerr (STREAM)' clears the 
error indicator for STREAM." which is in reverse order of what the text 
says - and either way the "Clears" of the comment disagrees with the 
"clear" of the function name.