[llvm-commits] [PATCH] Coding Standards: Doxygen guidelines

[Andrew Trick]

On Sep 14, 2012, at 8:27 AM, Dmitri Gribenko <gribozavr at gmail.com> wrote:

> Hello,
> 
> @Chris, Chandler: CC'ing you since this an addition to the policies
> and I feel like I need your review.
> 
> The attached patch documents current Doxygen use practices in Coding
> Standards.  Mostly it is obvious stuff and most new code being
> committed conforms to that.  Some old code does not; this might cause
> confusion and this is the motivation to document the correct
> guidelines.
> 
> Please review.

+Don't duplicate the documentation comment in header file and in implementation
+file.  If the API being documented is not module-private, documentation should
+go to the header file.

Sorry, this wasn't obvious to me, so I may be violating it in the short term until I understand the policy.

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.

-Andy