[cfe-dev] Doxygen comments duplicated in Clang source files : OK to delete them?
jordan_rose at apple.com
Tue Jul 3 17:26:40 PDT 2012
+1 from me on all points.
On Jul 3, 2012, at 5:07 PM, Chandler Carruth wrote:
> 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
> 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.
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
More information about the cfe-dev