<div class="gmail_extra"><div class="gmail_quote">I'll try to respond more fully today, but this has come up repeatedly, so I wanted to mention...</div><div class="gmail_quote"><br></div><div class="gmail_quote">On Fri, Sep 14, 2012 at 10:32 AM, Andrew Trick <span dir="ltr"><<a href="mailto:atrick@apple.com" target="_blank" class="cremed">atrick@apple.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im"><br>
On Sep 14, 2012, at 8:27 AM, Dmitri Gribenko <<a href="mailto:gribozavr@gmail.com" class="cremed">gribozavr@gmail.com</a>> wrote:<br>
<br>
> Hello,<br>
><br>
> @Chris, Chandler: CC'ing you since this an addition to the policies<br>
> and I feel like I need your review.<br>
><br>
> The attached patch documents current Doxygen use practices in Coding<br>
> Standards.  Mostly it is obvious stuff and most new code being<br>
> committed conforms to that.  Some old code does not; this might cause<br>
> confusion and this is the motivation to document the correct<br>
> guidelines.<br>
><br>
> Please review.<br>
<br>
</div>+Don't duplicate the documentation comment in header file and in implementation<br>
+file.  If the API being documented is not module-private, documentation should<br>
+go to the header file.<br>
<br>
Sorry, this wasn't obvious to me, so I may be violating it in the short term until I understand the policy.<br>
<br>
I'm definitely going to add function-level comments in the .cpp file. So should those detailed comments be doxygen style? The header comments are for people who need to understand the API. The out-of-line comments are for people hacking on the implementation. I often start by duplicating the short comment and refine it from there.<br>
</blockquote><div><br></div><div>I completely agree with your strategy here. The important distinction for me that I try not to duplicate anything from the actual interface comments by the time I finish. Having comments duplicated between the header and the source file results inevitably in them skewing over time and being inconsistent. Having *different* information (often as you say relevant to different readers) in the two locations I find very useful.</div>
<div><br></div><div>However, Chris has historically opposed this perspective and stated that he likes having a copy of the comment at the definition site even if it is a public interface with the same comment in the header file. This practice has confused numerous newcomers to Clang that I have seen, and has led to me finding a large number of contradictory comments within LLVM, so I'm hoping he'll reconsider this stance. ;] I can't actually find anyone that really agrees with him, but he can sort-of veto stuff, so let's see what he says.</div>
</div></div>