[cfe-dev] File header comments and Doxygen: to \file or not to \file, opinions?

[James Dennett]

On Tue, Jun 19, 2012 at 10:05 AM, Michael Spencer <bigcheesegs at gmail.com> wrote:
> On Tue, Jun 19, 2012 at 9:16 AM, Chandler Carruth <chandlerc at google.com> wrote:
>> On Mon, Jun 18, 2012 at 11:27 PM, James Dennett <jdennett at google.com> wrote:
>>>
>>> While cleaning up some of our Doxygen comments, I've changed some file
>>> header comments (a small number so far) to be Doxygen-friendly (so
>>> that the files have summaries in the generated docs), but I've now
>>> realized that deviates from the template mandated by
>>> http://llvm.org/docs/CodingStandards.html#scf_commenting.
>>>
>>> I'm looking to work out the best way forward (or at least a good way
>>> forward).  I'd prefer that we find a solution that allows for
>>> inclusion of "\file" documentation for Doxygen, and that avoids
>>> duplication with the existing documentation.  However, I'm aware that
>>> the files I've changed in this way are currently not consistent with
>>> others, or with the written policy, and I'm willing to revert those
>>> changes if necessary.
>>>
>>> Is it acceptable to convert files to use Doxygen markup for file-level
>>> comments, should I revert the changes I've made so far, advocate for
>>> updating the coding standards, or... other?
>>
>>
>> I think we can fit doxygen format *inside* the existing format:
>>
>> //===-- llvm/Instruction.h - Instruction class definition -------*- C++
>> -*-===//
>> //
>> //                     The LLVM Compiler Infrastructure
>> //
>> // This file is distributed under the University of Illinois Open Source
>> // License. See LICENSE.TXT for details.
>> //
>> //===----------------------------------------------------------------------===//
>> /// \file
>> ///
>> /// \briefThis file contains the declaration of the Instruction class, which
>> is the
>>
>> /// base class for all of the VM instructions.
>> ///
>> /// ...
>> ///
>> //===----------------------------------------------------------------------===//
>
> Agreed.
>
> - Michael Spencer

Looks good enough to me, I'll go with that.

Thanks.