<div style="font-family: arial, helvetica, sans-serif"><font size="2"><div class="gmail_quote">On Mon, Jun 18, 2012 at 11:27 PM, James Dennett <span dir="ltr"><<a href="mailto:jdennett@google.com" target="_blank">jdennett@google.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">While cleaning up some of our Doxygen comments, I've changed some file<br>
header comments (a small number so far) to be Doxygen-friendly (so<br>
that the files have summaries in the generated docs), but I've now<br>
realized that deviates from the template mandated by<br>
<a href="http://llvm.org/docs/CodingStandards.html#scf_commenting" target="_blank">http://llvm.org/docs/CodingStandards.html#scf_commenting</a>.<br>
<br>
I'm looking to work out the best way forward (or at least a good way<br>
forward).  I'd prefer that we find a solution that allows for<br>
inclusion of "\file" documentation for Doxygen, and that avoids<br>
duplication with the existing documentation.  However, I'm aware that<br>
the files I've changed in this way are currently not consistent with<br>
others, or with the written policy, and I'm willing to revert those<br>
changes if necessary.<br>
<br>
Is it acceptable to convert files to use Doxygen markup for file-level<br>
comments, should I revert the changes I've made so far, advocate for<br>
updating the coding standards, or... other?<br></blockquote><div><br></div><div>I think we can fit doxygen format *inside* the existing format:</div><div><br></div><font face="courier new, monospace">//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//<br>
//<br>//                     The LLVM Compiler Infrastructure<br>//<br>// This file is distributed under the University of Illinois Open Source<br>// License. See LICENSE.TXT for details.<br>//<br>//===----------------------------------------------------------------------===//<br>
/// \file</font></div><div class="gmail_quote"><font face="courier new, monospace">///<br>/// \briefThis file contains the declaration of the Instruction class, which is the<br>/// base class for all of the VM instructions.<br>
///</font></div><div class="gmail_quote"><font face="courier new, monospace">/// ...</font></div><div class="gmail_quote"><font face="courier new, monospace">///<br>//===----------------------------------------------------------------------===//</font></div>
<div class="gmail_quote"><font face="courier new, monospace"><br></font></div><div class="gmail_quote"><font face="courier new, monospace"><br></font><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<br>
while the Doxygen-ified version looks like<br>
<br>
//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//<br>
//<br>
//                     The LLVM Compiler Infrastructure<br>
//<br>
// This file is distributed under the University of Illinois Open Source<br>
// License. See LICENSE.TXT for details.<br>
//<br>
//===----------------------------------------------------------------------===//<br>
<br>
/// \file<br>
/// \brief Contains the declaration of the Instruction class, which is the<br>
/// base class for all of the VM instructions.<br>
<br>
The files affected so far are (at most):<br>
./lib/Parse/ParseExpr.cpp<br>
./lib/Sema/SemaExprCXX.cpp<br>
./include/clang/Lex/PreprocessorLexer.h<br>
./include/clang/Lex/PPCallbacks.h<br>
./include/clang/Lex/MultipleIncludeOpt.h<br>
./include/clang/Basic/SourceManager.h<br>
./include/clang/AST/StmtObjC.h<br>
./include/clang/AST/DeclTemplate.h<br>
./include/clang/Sema/DeclSpec.h<br>
<br>
Thanks in advance for any opinions.<br>
<br>
-- James<br>
<br>
_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev</a><br>
</blockquote></div><br></font></div>