<div class="gmail_extra"><div class="gmail_quote">On Tue, Jul 3, 2012 at 4:33 PM, James Dennett <span dir="ltr"><<a href="mailto:jdennett@google.com" target="_blank" class="cremed">jdennett@google.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">As I clean up a lot of Clang's comments for Doxygen's consumption, I'm<br>
hitting one issue repeatedly: a lot of the documentation is cut+pasted<br>
between the header file and the associated source file.  Apart from<br>
confusing some configurations of Doxygen (which concatenate the docs,<br>
giving duplication in the output), this inevitably leads to bitrot and<br>
divergence.<br></blockquote><div><br></div><div>I think the duplication is really bad, and I have a moderately strong preference for how to de-duplicate:</div><div><br></div><div>Public types, variables, functions, etc. should have doxygen comments on their declarations in the header.</div>
<div><br></div><div>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.</div><div><br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><br></div><div><br></div><div>Is this a pattern others are comfortable with?</div><div><br></div><div><br></div><div>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.</div>
<div><br></div><div>-Chandler</div></div></div>