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

[Chandler Carruth]

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



> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120619/7c410751/attachment.html>