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

[Jordan Rose]

+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
> 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
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev