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.
