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

[Chandler Carruth]

I'll try to respond more fully today, but this has come up repeatedly, so I
wanted to mention...

On Fri, Sep 14, 2012 at 10:32 AM, Andrew Trick <atrick at apple.com> wrote:

>
> 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.
>

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.

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120914/9cda8aa2/attachment.html>