[cfe-dev] Doxygen comments duplicated in Clang source files : OK to delete them?

[Chandler Carruth]

On Tue, Jul 3, 2012 at 4:33 PM, James Dennett <jdennett at google.com> wrote:

> As I clean up a lot of Clang's comments for Doxygen's consumption, I'm
> hitting one issue repeatedly: a lot of the documentation is cut+pasted
> between the header file and the associated source file.  Apart from
> confusing some configurations of Doxygen (which concatenate the docs,
> giving duplication in the output), this inevitably leads to bitrot and
> divergence.
>

I think the duplication is really bad, and I have a moderately strong
preference for how to de-duplicate:

Public types, variables, functions, etc. should have doxygen comments on
their declarations in the header.

Private types, variables, functions, etc. should have doxygen comments in
the definitions only, either in the source file or in an out-of-line
definition in the header.

This isn't necessarily the C++ definition of "public" or "private" but
more, the intended interpretation for users of the code: If it's part of
the interface that is intended to be used by consumers, document it in the
header. If it's ostensibly part of the implementation, document it in the
source file.

Also, clearly private member variables or private inline functions can't
have this rule applied to them. But in those cases, there is no ambiguity
or choice in the matter -- everything is necessarily attached to the single
declaration/definition.


Is this a pattern others are comfortable with?


Whenever we reach a consensus, James, would you be up for contributing a
patch adding advice about this to the LLVM coding conventions? We should
document the resolution of these issues.

-Chandler
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120703/009117c3/attachment.html>