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

[Michael Spencer]

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

>
>>
>> while the Doxygen-ified version looks like
>>
>> //===-- 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
>> /// \brief Contains the declaration of the Instruction class, which is the
>> /// base class for all of the VM instructions.
>>
>> The files affected so far are (at most):
>> ./lib/Parse/ParseExpr.cpp
>> ./lib/Sema/SemaExprCXX.cpp
>> ./include/clang/Lex/PreprocessorLexer.h
>> ./include/clang/Lex/PPCallbacks.h
>> ./include/clang/Lex/MultipleIncludeOpt.h
>> ./include/clang/Basic/SourceManager.h
>> ./include/clang/AST/StmtObjC.h
>> ./include/clang/AST/DeclTemplate.h
>> ./include/clang/Sema/DeclSpec.h
>>
>> Thanks in advance for any opinions.
>>
>> -- James
>>
>> _______________________________________________
>> cfe-dev mailing list
>> cfe-dev at cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>
>
>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>