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

[James Dennett]

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?

Concretely, the mandated format is

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