fix doxygen brief in subzero header files
There is a consistent mistake in most of the file level subzero doxygen
comments which stems from a problem with brief.
Basically, there are two types of documentation in Doxygen, inline and
structural documentation. File level documentation is always structural
because inline documentation must either come before or after the entity
and for a file that would be impossible.
When you have structure documentation, the brief and detailed is
handled differently and you have to explicity put the \brief qualifier in.
We were only doing this for a few files so when you looked the doxygen
for the source directory, the description was blank for almost all of them.
If you build docs with this patch and look at the "files" and src
directory, you will see all the brief descriptions now.
In addition I deleted the text "This file ..." from the
beginning of all the file desriptions because it's redundant when you look at the doxygen output and adds
no information but takes up space in the descripton.
BUG=
R=stichnot@chromium.org
Review URL: https://codereview.chromium.org/1488913002 .
diff --git a/src/IceAssembler.cpp b/src/IceAssembler.cpp
index 480eb30..04cb949 100644
--- a/src/IceAssembler.cpp
+++ b/src/IceAssembler.cpp
@@ -19,7 +19,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Assembler base class.
+/// \brief Implements the Assembler base class.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceAssembler.h b/src/IceAssembler.h
index 599a0a0..d80e3d2 100644
--- a/src/IceAssembler.h
+++ b/src/IceAssembler.h
@@ -15,9 +15,11 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the Assembler base class. Instructions are assembled by
-/// architecture-specific assemblers that derive from this base class. This base
-/// class manages buffers and fixups for emitting code, etc.
+/// \brief Declares the Assembler base class.
+///
+/// Instructions are assembled by architecture-specific assemblers that derive
+/// from this base class. This base class manages buffers and fixups for
+/// emitting code, etc.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceAssemblerARM32.cpp b/src/IceAssemblerARM32.cpp
index c92483e..6b6dea5 100644
--- a/src/IceAssemblerARM32.cpp
+++ b/src/IceAssemblerARM32.cpp
@@ -16,7 +16,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Assembler class for ARM32.
+/// \brief Implements the Assembler class for ARM32.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceAssemblerARM32.h b/src/IceAssemblerARM32.h
index 3ad3834..4d8a575 100644
--- a/src/IceAssemblerARM32.h
+++ b/src/IceAssemblerARM32.h
@@ -16,7 +16,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Assembler class for ARM32.
+/// \brief Declares the Assembler class for ARM32.
///
/// Note: All references to ARM "section" documentation refers to the "ARM
/// Architecture Reference Manual, ARMv7-A and ARMv7-R edition". See:
diff --git a/src/IceAssemblerMIPS32.h b/src/IceAssemblerMIPS32.h
index 1d46b91..08cbd42 100644
--- a/src/IceAssemblerMIPS32.h
+++ b/src/IceAssemblerMIPS32.h
@@ -16,7 +16,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Assembler class for MIPS32.
+/// \brief Declares the Assembler class for MIPS32.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceAssemblerX8632.h b/src/IceAssemblerX8632.h
index fb9eedf..2ce694c 100644
--- a/src/IceAssemblerX8632.h
+++ b/src/IceAssemblerX8632.h
@@ -16,7 +16,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Assembler class for x86-32.
+/// \brief Implements the Assembler class for x86-32.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceAssemblerX8664.h b/src/IceAssemblerX8664.h
index 5666810..7e6ae05 100644
--- a/src/IceAssemblerX8664.h
+++ b/src/IceAssemblerX8664.h
@@ -16,7 +16,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Assembler class for x86-64.
+/// \brief Implements the Assembler class for x86-64.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceAssemblerX86Base.h b/src/IceAssemblerX86Base.h
index 3823f0d..4b9d9b9 100644
--- a/src/IceAssemblerX86Base.h
+++ b/src/IceAssemblerX86Base.h
@@ -15,8 +15,9 @@
//
//===----------------------------------------------------------------------===//
//
-// This file defines the AssemblerX86 template class for x86, the base of all
-// X86 assemblers.
+/// \file
+/// \brief Defines the AssemblerX86 template class for x86, the base of all X86
+/// assemblers.
//
//===----------------------------------------------------------------------===//
diff --git a/src/IceAssemblerX86BaseImpl.h b/src/IceAssemblerX86BaseImpl.h
index a72f266..f48529a 100644
--- a/src/IceAssemblerX86BaseImpl.h
+++ b/src/IceAssemblerX86BaseImpl.h
@@ -14,8 +14,9 @@
//
//===----------------------------------------------------------------------===//
//
-// This file implements the AssemblerX86Base template class, which is the base
-// Assembler class for X86 assemblers.
+/// \file
+/// \brief Implements the AssemblerX86Base template class, which is the base
+/// Assembler class for X86 assemblers.
//
//===----------------------------------------------------------------------===//
diff --git a/src/IceBrowserCompileServer.cpp b/src/IceBrowserCompileServer.cpp
index 94b991a..469e56d 100644
--- a/src/IceBrowserCompileServer.cpp
+++ b/src/IceBrowserCompileServer.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines the browser-based compile server.
+/// \brief Defines the browser-based compile server.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceBrowserCompileServer.h b/src/IceBrowserCompileServer.h
index f23ab17..ce3f60d 100644
--- a/src/IceBrowserCompileServer.h
+++ b/src/IceBrowserCompileServer.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the browser-specific compile server.
+/// \brief Declares the browser-based compile server.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceBuildDefs.h b/src/IceBuildDefs.h
index 71600d4..6714297 100644
--- a/src/IceBuildDefs.h
+++ b/src/IceBuildDefs.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines constexpr functions to query various #define values.
+/// \brief Defines constexpr functions to query various #define values.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceCfg.cpp b/src/IceCfg.cpp
index f8d40a5..dd8416f 100644
--- a/src/IceCfg.cpp
+++ b/src/IceCfg.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Cfg class, including constant pool management.
+/// \brief Implements the Cfg class.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceCfg.h b/src/IceCfg.h
index f88aa5f..b7a7ce4 100644
--- a/src/IceCfg.h
+++ b/src/IceCfg.h
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the Cfg class, which represents the control flow graph
-/// and the overall per-function compilation context.
+/// \brief Declares the Cfg class, which represents the control flow graph and
+/// the overall per-function compilation context.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceCfgNode.cpp b/src/IceCfgNode.cpp
index a105e91..0b9b79b 100644
--- a/src/IceCfgNode.cpp
+++ b/src/IceCfgNode.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the CfgNode class, including the complexities of
+/// \brief Implements the CfgNode class, including the complexities of
/// instruction insertion and in-edge calculation.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceCfgNode.h b/src/IceCfgNode.h
index dbc2cce..4a27af6 100644
--- a/src/IceCfgNode.h
+++ b/src/IceCfgNode.h
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the CfgNode class, which represents a single basic block
-/// as its instruction list, in-edge list, and out-edge list.
+/// \brief Declares the CfgNode class, which represents a single basic block as
+/// its instruction list, in-edge list, and out-edge list.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceClFlags.cpp b/src/IceClFlags.cpp
index 6966210..b922d40 100644
--- a/src/IceClFlags.cpp
+++ b/src/IceClFlags.cpp
@@ -8,9 +8,10 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines commandline flags parsing. This currently relies on
-/// llvm::cl to parse. In the future, the minimal build can have a simpler
-/// parser.
+/// \brief Defines commandline flags parsing.
+///
+/// This currently relies on llvm::cl to parse. In the future, the minimal build
+/// can have a simpler parser.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceClFlags.h b/src/IceClFlags.h
index 1072bd0..a514a9b 100644
--- a/src/IceClFlags.h
+++ b/src/IceClFlags.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares command line flags controlling translation.
+/// \brief Declares command line flags controlling translation.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceClFlagsExtra.h b/src/IceClFlagsExtra.h
index 8086dc9..2204414 100644
--- a/src/IceClFlagsExtra.h
+++ b/src/IceClFlagsExtra.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares command line flags primarily used for non-minimal builds.
+/// \brief Declares command line flags primarily used for non-minimal builds.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceCompileServer.cpp b/src/IceCompileServer.cpp
index 49c7ab8..1da36b5 100644
--- a/src/IceCompileServer.cpp
+++ b/src/IceCompileServer.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines the basic commandline-based compile server.
+/// \brief Defines the basic commandline-based compile server.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceCompileServer.h b/src/IceCompileServer.h
index 8d99927..9b02f92 100644
--- a/src/IceCompileServer.h
+++ b/src/IceCompileServer.h
@@ -8,8 +8,10 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the compile server. Given a compiler implementation, it
-/// dispatches compile requests to the implementation.
+/// \brief Declares the compile server.
+///
+/// Given a compiler implementation, it dispatches compile requests to the
+/// implementation.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceCompiler.cpp b/src/IceCompiler.cpp
index fdd9756..adccfd2 100644
--- a/src/IceCompiler.cpp
+++ b/src/IceCompiler.cpp
@@ -8,11 +8,12 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines a driver for translating PNaCl bitcode into native code.
-/// It can either directly parse the binary bitcode file, or use LLVM routines
-/// to parse a textual bitcode file into LLVM IR and then convert LLVM IR into
-/// ICE. In either case, the high-level ICE is then compiled down to native
-/// code, as either an ELF object file or a textual asm file.
+/// \brief Defines a driver for translating PNaCl bitcode into native code.
+///
+/// The driver can either directly parse the binary bitcode file, or use LLVM
+/// routines to parse a textual bitcode file into LLVM IR and then convert LLVM
+/// IR into ICE. In either case, the high-level ICE is then compiled down to
+/// native code, as either an ELF object file or a textual asm file.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceCompiler.h b/src/IceCompiler.h
index 6239b9f..906263a 100644
--- a/src/IceCompiler.h
+++ b/src/IceCompiler.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the driver for translating bitcode to native code.
+/// \brief Declares the driver for translating bitcode to native code.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceConditionCodesARM32.h b/src/IceConditionCodesARM32.h
index d739310..e7fc4d0 100644
--- a/src/IceConditionCodesARM32.h
+++ b/src/IceConditionCodesARM32.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the condition codes for ARM32.
+/// \brief Declares the condition codes for ARM32.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceConditionCodesX8632.h b/src/IceConditionCodesX8632.h
index e17bf69..08f6838 100644
--- a/src/IceConditionCodesX8632.h
+++ b/src/IceConditionCodesX8632.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the condition codes for x86-32.
+/// \brief Declares the condition codes for x86-32.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceConditionCodesX8664.h b/src/IceConditionCodesX8664.h
index 1875beb..f0efd50 100644
--- a/src/IceConditionCodesX8664.h
+++ b/src/IceConditionCodesX8664.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the condition codes for x86-64.
+/// \brief Declares the condition codes for x86-64.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceConverter.cpp b/src/IceConverter.cpp
index 34bdcb9..9ed808e 100644
--- a/src/IceConverter.cpp
+++ b/src/IceConverter.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the LLVM to ICE converter.
+/// \brief Implements the LLVM to ICE converter.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceConverter.h b/src/IceConverter.h
index accc554..22288af 100644
--- a/src/IceConverter.h
+++ b/src/IceConverter.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the LLVM to ICE converter.
+/// \brief Declares the LLVM to ICE converter.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceDefs.h b/src/IceDefs.h
index 6fd73f5..ceb6fd0 100644
--- a/src/IceDefs.h
+++ b/src/IceDefs.h
@@ -8,8 +8,10 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares various useful types and classes that have widespread use
-/// across Subzero. Every Subzero source file is expected to include IceDefs.h.
+/// \brief Declares various useful types and classes that have widespread use
+/// across Subzero.
+///
+/// Every Subzero source file is expected to include IceDefs.h.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceELFObjectWriter.cpp b/src/IceELFObjectWriter.cpp
index 2ea97d7..5d81635 100644
--- a/src/IceELFObjectWriter.cpp
+++ b/src/IceELFObjectWriter.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines the writer for ELF relocatable object files.
+/// \brief Defines the writer for ELF relocatable object files.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceELFObjectWriter.h b/src/IceELFObjectWriter.h
index 60ed60c..f2171b1 100644
--- a/src/IceELFObjectWriter.h
+++ b/src/IceELFObjectWriter.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// Abstraction for a writer that is responsible for writing an ELF file.
+/// \brief Abstraction for a writer that is responsible for writing an ELF file.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceELFSection.cpp b/src/IceELFSection.cpp
index 3768150..cf5c733 100644
--- a/src/IceELFSection.cpp
+++ b/src/IceELFSection.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines how ELF sections are represented.
+/// \brief Defines how ELF sections are represented.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceELFSection.h b/src/IceELFSection.h
index 636f3b4..6d24e4a 100644
--- a/src/IceELFSection.h
+++ b/src/IceELFSection.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// Representation of ELF sections.
+/// \brief Representation of ELF sections.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceELFStreamer.h b/src/IceELFStreamer.h
index ab99891..a1c9b94 100644
--- a/src/IceELFStreamer.h
+++ b/src/IceELFStreamer.h
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// Interface for serializing bits for common ELF types (words, extended words,
-/// etc.), based on the ELF Class.
+/// \brief Interface for serializing bits for common ELF types (words, extended
+/// words, etc.), based on the ELF class.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceFixups.cpp b/src/IceFixups.cpp
index 305e695..59bd4f3 100644
--- a/src/IceFixups.cpp
+++ b/src/IceFixups.cpp
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the AssemblerFixup class, a very basic
-/// target-independent representation of a fixup or relocation.
+/// \brief Implements the AssemblerFixup class, a very basic target-independent
+/// representation of a fixup or relocation.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceFixups.h b/src/IceFixups.h
index aaef7ab..a83a00e 100644
--- a/src/IceFixups.h
+++ b/src/IceFixups.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares generic fixup types.
+/// \brief Declares generic fixup types.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceGlobalContext.cpp b/src/IceGlobalContext.cpp
index 94a5343..f18b0ef 100644
--- a/src/IceGlobalContext.cpp
+++ b/src/IceGlobalContext.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines aspects of the compilation that persist across multiple
+/// \brief Defines aspects of the compilation that persist across multiple
/// functions.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceGlobalContext.h b/src/IceGlobalContext.h
index 11e0daa..ec4e717 100644
--- a/src/IceGlobalContext.h
+++ b/src/IceGlobalContext.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares aspects of the compilation that persist across multiple
+/// \brief Declares aspects of the compilation that persist across multiple
/// functions.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceGlobalInits.cpp b/src/IceGlobalInits.cpp
index 2c1460a..ab53eac 100644
--- a/src/IceGlobalInits.cpp
+++ b/src/IceGlobalInits.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the notion of function declarations, global variable
+/// \brief Implements the notion of function declarations, global variable
/// declarations, and the corresponding variable initializers in Subzero.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceGlobalInits.h b/src/IceGlobalInits.h
index 82e5cde..3a19f47 100644
--- a/src/IceGlobalInits.h
+++ b/src/IceGlobalInits.h
@@ -8,10 +8,11 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the representation of function declarations, global
-/// variable declarations, and the corresponding variable initializers in
-/// Subzero. Global variable initializers are represented as a sequence of
-/// simple initializers.
+/// \brief Declares the representation of function declarations, global variable
+/// declarations, and the corresponding variable initializers in Subzero.
+///
+/// Global variable initializers are represented as a sequence of simple
+/// initializers.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceInst.cpp b/src/IceInst.cpp
index 2946296..6fb8780 100644
--- a/src/IceInst.cpp
+++ b/src/IceInst.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Inst class, primarily the various subclass
+/// \brief Implements the Inst class, primarily the various subclass
/// constructors and dump routines.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceInst.h b/src/IceInst.h
index a04584e..f9265f6 100644
--- a/src/IceInst.h
+++ b/src/IceInst.h
@@ -8,9 +8,10 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the Inst class and its target-independent
-/// subclasses, which represent the high-level Vanilla ICE instructions
-/// and map roughly 1:1 to LLVM instructions.
+/// \brief Declares the Inst class and its target-independent subclasses.
+///
+/// These represent the high-level Vanilla ICE instructions and map roughly 1:1
+/// to LLVM instructions.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceInstARM32.cpp b/src/IceInstARM32.cpp
index 2c2b210..d177891 100644
--- a/src/IceInstARM32.cpp
+++ b/src/IceInstARM32.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the InstARM32 and OperandARM32 classes, primarily the
+/// \brief Implements the InstARM32 and OperandARM32 classes, primarily the
/// constructors and the dump()/emit() methods.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceInstARM32.h b/src/IceInstARM32.h
index 316dc93..138fd84 100644
--- a/src/IceInstARM32.h
+++ b/src/IceInstARM32.h
@@ -8,9 +8,10 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the InstARM32 and OperandARM32 classes and their
-/// subclasses. This represents the machine instructions and operands used for
-/// ARM32 code selection.
+/// \brief Declares the InstARM32 and OperandARM32 classes and their subclasses.
+///
+/// This represents the machine instructions and operands used for ARM32 code
+/// selection.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceInstMIPS32.cpp b/src/IceInstMIPS32.cpp
index 4f394d6..2c7ee90 100644
--- a/src/IceInstMIPS32.cpp
+++ b/src/IceInstMIPS32.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
//
/// \file
-/// This file implements the InstMips32 and OperandMips32 classes, primarily the
+/// \brief Implements the InstMips32 and OperandMips32 classes, primarily the
/// constructors and the dump()/emit() methods.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceInstMIPS32.h b/src/IceInstMIPS32.h
index 952fd47..acd7bfd 100644
--- a/src/IceInstMIPS32.h
+++ b/src/IceInstMIPS32.h
@@ -8,9 +8,11 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the InstMIPS32 and OperandMIPS32 classes and their
-/// subclasses. This represents the machine instructions and operands used for
-/// MIPS32 code selection.
+/// \brief Declares the InstMIPS32 and OperandMIPS32 classes and their
+/// subclasses.
+///
+/// This represents the machine instructions and operands used for MIPS32 code
+/// selection.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceInstVarIter.h b/src/IceInstVarIter.h
index 4a2c31b..b598e18 100644
--- a/src/IceInstVarIter.h
+++ b/src/IceInstVarIter.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines a common pattern for iterating over the variables of an
+/// \brief Defines a common pattern for iterating over the variables of an
/// instruction.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceInstX8632.cpp b/src/IceInstX8632.cpp
index 7c9e855..446651f 100644
--- a/src/IceInstX8632.cpp
+++ b/src/IceInstX8632.cpp
@@ -8,11 +8,11 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines X8632 specific data related to X8632 Instructions and
-/// Instruction traits. These are declared in the IceTargetLoweringX8632Traits.h
-/// header file.
+/// \brief Defines X8632 specific data related to X8632 Instructions and
+/// Instruction traits.
///
-/// This file also defines X8632 operand specific methods (dump and emit.)
+/// These are declared in the IceTargetLoweringX8632Traits.h header file. This
+/// file also defines X8632 operand specific methods (dump and emit.)
///
//===----------------------------------------------------------------------===//
#include "IceInstX8632.h"
diff --git a/src/IceInstX8632.h b/src/IceInstX8632.h
index d765660..00d18a0 100644
--- a/src/IceInstX8632.h
+++ b/src/IceInstX8632.h
@@ -8,9 +8,10 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file used to house all the X8632 instructions. Subzero has been
-/// modified to use templates for X86 instructions, so all those definitions are
-/// are in IceInstX86Base.h
+/// \brief Used to house all the X8632 instructions.
+///
+/// Subzero has been modified to use templates for X86 instructions, so all
+/// those definitions are are in IceInstX86Base.h
///
/// When interacting with the X8632 target (which should only happen in the
/// X8632 TargetLowering) clients have should use the Ice::X8632::Traits::Insts
diff --git a/src/IceInstX8664.cpp b/src/IceInstX8664.cpp
index 88785a6..7ca6196 100644
--- a/src/IceInstX8664.cpp
+++ b/src/IceInstX8664.cpp
@@ -8,9 +8,10 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines X8664 specific data related to X8664 Instructions and
-/// Instruction traits. These are declared in the IceTargetLoweringX8664Traits.h
-/// header file.
+/// \brief This file defines X8664 specific data related to X8664 Instructions
+/// and Instruction traits.
+///
+/// These are declared in the IceTargetLoweringX8664Traits.h header file.
///
/// This file also defines X8664 operand specific methods (dump and emit.)
///
diff --git a/src/IceInstX8664.h b/src/IceInstX8664.h
index 2520b75..e71255e 100644
--- a/src/IceInstX8664.h
+++ b/src/IceInstX8664.h
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// (Note: x86 instructions are templates, and they are defined in
-/// src/IceInstX86Base.)
+/// \brief (Note: x86 instructions are templates, and they are defined in
+/// src/IceInstX86Base.)
///
/// When interacting with the X8664 target (which should only happen in the
/// X8664 TargetLowering) clients have should use the Ice::X8664::Traits::Insts
diff --git a/src/IceInstX86Base.h b/src/IceInstX86Base.h
index 6e9d7ba..9c9ebf7 100644
--- a/src/IceInstX86Base.h
+++ b/src/IceInstX86Base.h
@@ -8,10 +8,11 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines the InstX86Base template class, as well as the generic X86
-/// Instruction class hierarchy. Only X86 instructions common across all/most
-/// X86 targets should be defined here, with target-specific instructions
-/// declared in the target's traits.
+/// \brief This file defines the InstX86Base template class, as well as the
+/// generic X86 Instruction class hierarchy.
+///
+/// Only X86 instructions common across all/most X86 targets should be defined
+/// here, with target-specific instructions declared in the target's traits.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceInstX86BaseImpl.h b/src/IceInstX86BaseImpl.h
index 2fbd8c8..84ff8dc 100644
--- a/src/IceInstX86BaseImpl.h
+++ b/src/IceInstX86BaseImpl.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the InstX86Base class and its descendants.
+/// \brief Implements the InstX86Base class and its descendants.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceIntrinsics.cpp b/src/IceIntrinsics.cpp
index 123817d..94e582f 100644
--- a/src/IceIntrinsics.cpp
+++ b/src/IceIntrinsics.cpp
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Intrinsics utilities for matching and then
-/// dispatching by name.
+/// \brief Implements the Intrinsics utilities for matching and then dispatching
+/// by name.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceIntrinsics.h b/src/IceIntrinsics.h
index 11db543..2bd1a68 100644
--- a/src/IceIntrinsics.h
+++ b/src/IceIntrinsics.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the kinds of intrinsics supported by PNaCl.
+/// \brief Declares the kinds of intrinsics supported by PNaCl.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceLiveness.cpp b/src/IceLiveness.cpp
index 25cfd09..2bfa624 100644
--- a/src/IceLiveness.cpp
+++ b/src/IceLiveness.cpp
@@ -8,14 +8,15 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file provides some of the support for the Liveness class. In
-/// particular, it handles the sparsity representation of the mapping between
-/// Variables and CfgNodes. The idea is that since most variables are used only
-/// within a single basic block, we can partition the variables into "local" and
-/// "global" sets. Instead of sizing and indexing vectors according to
-/// Variable::Number, we create a mapping such that global variables are mapped
-/// to low indexes that are common across nodes, and local variables are mapped
-/// to a higher index space that is shared across nodes.
+/// \brief Provides some of the support for the Liveness class.
+
+/// In particular, it handles the sparsity representation of the mapping
+/// between Variables and CfgNodes. The idea is that since most variables are
+/// used only within a single basic block, we can partition the variables into
+/// "local" and "global" sets. Instead of sizing and indexing vectors according
+/// to Variable::Number, we create a mapping such that global variables are
+/// mapped to low indexes that are common across nodes, and local variables are
+/// mapped to a higher index space that is shared across nodes.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceLiveness.h b/src/IceLiveness.h
index 535ed02..a51a28d 100644
--- a/src/IceLiveness.h
+++ b/src/IceLiveness.h
@@ -8,12 +8,13 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the Liveness and LivenessNode classes, which are used for
-/// liveness analysis. The node-specific information tracked for each Variable
-/// includes whether it is live on entry, whether it is live on exit, the
-/// instruction number that starts its live range, and the instruction number
-/// that ends its live range. At the Cfg level, the actual live intervals are
-/// recorded.
+/// \brief Declares the Liveness and LivenessNode classes, which are used for
+/// liveness analysis.
+///
+/// The node-specific information tracked for each Variable includes whether it
+/// is live on entry, whether it is live on exit, the instruction number that
+/// starts its live range, and the instruction number that ends its live range.
+/// At the Cfg level, the actual live intervals are recorded.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceLoopAnalyzer.cpp b/src/IceLoopAnalyzer.cpp
index 17aaaf1..a76dfe2 100644
--- a/src/IceLoopAnalyzer.cpp
+++ b/src/IceLoopAnalyzer.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the loop analysis on the CFG.
+/// \brief Implements the loop analysis on the CFG.
///
//===----------------------------------------------------------------------===//
#include "IceLoopAnalyzer.h"
diff --git a/src/IceOperand.cpp b/src/IceOperand.cpp
index bb16967..b46c7f5 100644
--- a/src/IceOperand.cpp
+++ b/src/IceOperand.cpp
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the Operand class and its target-independent
-/// subclasses, primarily for the methods of the Variable class.
+/// \brief Implements the Operand class and its target-independent subclasses,
+/// primarily for the methods of the Variable class.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceOperand.h b/src/IceOperand.h
index 0cde5b2..7398f73 100644
--- a/src/IceOperand.h
+++ b/src/IceOperand.h
@@ -8,7 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the Operand class and its target-independent subclasses.
+/// \brief Declares the Operand class and its target-independent subclasses.
+///
/// The main classes are Variable, which represents an LLVM variable that is
/// either register- or stack-allocated, and the Constant hierarchy, which
/// represents integer, floating-point, and/or symbolic constants.
diff --git a/src/IcePhiLoweringImpl.h b/src/IcePhiLoweringImpl.h
index d65620e..512b1f9 100644
--- a/src/IcePhiLoweringImpl.h
+++ b/src/IcePhiLoweringImpl.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This contains utilities for targets to lower Phis.
+/// \brief Utilities for targets to lower Phis.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceRNG.cpp b/src/IceRNG.cpp
index 987d1a4..1a5f8ef 100644
--- a/src/IceRNG.cpp
+++ b/src/IceRNG.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the random number generator.
+/// \brief Implements the random number generator.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceRNG.h b/src/IceRNG.h
index 7ee2e39..15a3dee 100644
--- a/src/IceRNG.h
+++ b/src/IceRNG.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares a random number generator.
+/// \brief Declares a random number generator.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceRegAlloc.cpp b/src/IceRegAlloc.cpp
index cbe59b7..3299b71 100644
--- a/src/IceRegAlloc.cpp
+++ b/src/IceRegAlloc.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the LinearScan class, which performs the linear-scan
+/// \brief Implements the LinearScan class, which performs the linear-scan
/// register allocation after liveness analysis has been performed.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceRegAlloc.h b/src/IceRegAlloc.h
index 8faacc7..2776f5b 100644
--- a/src/IceRegAlloc.h
+++ b/src/IceRegAlloc.h
@@ -8,9 +8,10 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the LinearScan data structure used during linear-scan
-/// register allocation, which holds the various work queues for the linear-scan
-/// algorithm.
+/// \brief Declares the LinearScan data structure used during linear-scan
+/// register allocation.
+///
+/// This holds the various work queues for the linear-scan algorithm.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceRegList.h b/src/IceRegList.h
index 4b21044..bba8491 100644
--- a/src/IceRegList.h
+++ b/src/IceRegList.h
@@ -7,8 +7,9 @@
//
//===----------------------------------------------------------------------===//
//
-// This file defines the REGLIST*() macros used in the IceInst*.def files.
-//
+/// \file
+/// \brief Defines the REGLIST*() macros used in the IceInst*.def files.
+///
//===----------------------------------------------------------------------===//
#ifndef SUBZERO_SRC_ICEINSTREGLIST_H
diff --git a/src/IceRegistersARM32.h b/src/IceRegistersARM32.h
index 64dcf0d..3104f96 100644
--- a/src/IceRegistersARM32.h
+++ b/src/IceRegistersARM32.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the registers and their encodings for ARM32.
+/// \brief Declares the registers and their encodings for ARM32.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceRegistersMIPS32.h b/src/IceRegistersMIPS32.h
index 38335f8..1dcceb7 100644
--- a/src/IceRegistersMIPS32.h
+++ b/src/IceRegistersMIPS32.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the registers and their encodings for MIPS32.
+/// \brief Declares the registers and their encodings for MIPS32.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceRegistersX8632.h b/src/IceRegistersX8632.h
index 3fa07f8..5d71aa7 100644
--- a/src/IceRegistersX8632.h
+++ b/src/IceRegistersX8632.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the registers and their encodings for x86-32.
+/// \brief Declares the registers and their encodings for x86-32.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceRegistersX8664.h b/src/IceRegistersX8664.h
index d9ca1f9..7587995 100644
--- a/src/IceRegistersX8664.h
+++ b/src/IceRegistersX8664.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the registers and their encodings for x86-64.
+/// \brief Declares the registers and their encodings for x86-64.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceSwitchLowering.cpp b/src/IceSwitchLowering.cpp
index 047aa91..7861df2 100644
--- a/src/IceSwitchLowering.cpp
+++ b/src/IceSwitchLowering.cpp
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements platform independent analysis of switch cases to
-/// improve the generated code.
+/// \brief Implements platform independent analysis of switch cases to improve
+/// the generated code.
///
//===----------------------------------------------------------------------===//
#include "IceSwitchLowering.h"
diff --git a/src/IceSwitchLowering.h b/src/IceSwitchLowering.h
index fc9c4a2..380626b 100644
--- a/src/IceSwitchLowering.h
+++ b/src/IceSwitchLowering.h
@@ -8,7 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// \brief The file contains helpers for switch lowering.
+/// \brief Helpers for switch lowering.
+///
//===----------------------------------------------------------------------===//
#ifndef SUBZERO_SRC_ICESWITCHLOWERING_H
diff --git a/src/IceTLS.h b/src/IceTLS.h
index 5b9a8e8..73d7504 100644
--- a/src/IceTLS.h
+++ b/src/IceTLS.h
@@ -8,9 +8,11 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines macros for working around the lack of support for
-/// thread_local in MacOS 10.6. It assumes std::thread is written in terms of
-/// pthread. Define ICE_THREAD_LOCAL_HACK to enable the pthread workarounds.
+/// \brief Defines macros for working around the lack of support for
+/// thread_local in MacOS 10.6.
+///
+/// This assumes std::thread is written in terms of pthread. Define
+/// ICE_THREAD_LOCAL_HACK to enable the pthread workarounds.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLowering.cpp b/src/IceTargetLowering.cpp
index a5bd86b..171882d 100644
--- a/src/IceTargetLowering.cpp
+++ b/src/IceTargetLowering.cpp
@@ -8,10 +8,11 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the skeleton of the TargetLowering class, specifically
-/// invoking the appropriate lowering method for a given instruction kind and
-/// driving global register allocation. It also implements the non-deleted
-/// instruction iteration in LoweringContext.
+/// \brief Implements the skeleton of the TargetLowering class.
+///
+/// Specifically this invokes the appropriate lowering method for a given
+/// instruction kind and driving global register allocation. It also implements
+/// the non-deleted instruction iteration in LoweringContext.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLowering.h b/src/IceTargetLowering.h
index dbfe669..045173b 100644
--- a/src/IceTargetLowering.h
+++ b/src/IceTargetLowering.h
@@ -8,13 +8,15 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the TargetLowering, LoweringContext, and
-/// TargetDataLowering classes. TargetLowering is an abstract class used to
-/// drive the translation/lowering process. LoweringContext maintains a context
-/// for lowering each instruction, offering conveniences such as iterating over
-/// non-deleted instructions. TargetDataLowering is an abstract class used to
-/// drive the lowering/emission of global initializers, external global
-/// declarations, and internal constant pools.
+/// \brief Declares the TargetLowering, LoweringContext, and TargetDataLowering
+/// classes.
+///
+/// TargetLowering is an abstract class used to drive the translation/lowering
+/// process. LoweringContext maintains a context for lowering each instruction,
+/// offering conveniences such as iterating over non-deleted instructions.
+/// TargetDataLowering is an abstract class used to drive the lowering/emission
+/// of global initializers, external global declarations, and internal constant
+/// pools.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringARM32.cpp b/src/IceTargetLoweringARM32.cpp
index b714f7b..76fc99e 100644
--- a/src/IceTargetLoweringARM32.cpp
+++ b/src/IceTargetLoweringARM32.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the TargetLoweringARM32 class, which consists almost
+/// \brief Implements the TargetLoweringARM32 class, which consists almost
/// entirely of the lowering sequence for each high-level instruction.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringARM32.h b/src/IceTargetLoweringARM32.h
index 2f7cc9f..b0a9402 100644
--- a/src/IceTargetLoweringARM32.h
+++ b/src/IceTargetLoweringARM32.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the TargetLoweringARM32 class, which implements the
+/// \brief Declares the TargetLoweringARM32 class, which implements the
/// TargetLowering interface for the ARM 32-bit architecture.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringMIPS32.cpp b/src/IceTargetLoweringMIPS32.cpp
index 9f1aea6..7ce803b 100644
--- a/src/IceTargetLoweringMIPS32.cpp
+++ b/src/IceTargetLoweringMIPS32.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the TargetLoweringMIPS32 class, which consists almost
+/// \brief Implements the TargetLoweringMIPS32 class, which consists almost
/// entirely of the lowering sequence for each high-level instruction.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringMIPS32.h b/src/IceTargetLoweringMIPS32.h
index 387ec2e..bf96661 100644
--- a/src/IceTargetLoweringMIPS32.h
+++ b/src/IceTargetLoweringMIPS32.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the TargetLoweringMIPS32 class, which implements the
+/// \brief Declares the TargetLoweringMIPS32 class, which implements the
/// TargetLowering interface for the MIPS 32-bit architecture.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringX8632.cpp b/src/IceTargetLoweringX8632.cpp
index 198273b..0019693 100644
--- a/src/IceTargetLoweringX8632.cpp
+++ b/src/IceTargetLoweringX8632.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the TargetLoweringX8632 class, which consists almost
+/// \brief Implements the TargetLoweringX8632 class, which consists almost
/// entirely of the lowering sequence for each high-level instruction.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringX8632.h b/src/IceTargetLoweringX8632.h
index b1d74f5..d2c36e9 100644
--- a/src/IceTargetLoweringX8632.h
+++ b/src/IceTargetLoweringX8632.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the TargetLoweringX8632 class, which implements the
+/// \brief Declares the TargetLoweringX8632 class, which implements the
/// TargetLowering interface for the x86-32 architecture.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringX8632Traits.h b/src/IceTargetLoweringX8632Traits.h
index 06c3644..83db676 100644
--- a/src/IceTargetLoweringX8632Traits.h
+++ b/src/IceTargetLoweringX8632Traits.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the X8632 Target Lowering Traits.
+/// \brief Declares the X8632 Target Lowering Traits.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringX8664.cpp b/src/IceTargetLoweringX8664.cpp
index c169242..ceaaede 100644
--- a/src/IceTargetLoweringX8664.cpp
+++ b/src/IceTargetLoweringX8664.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the TargetLoweringX8664 class, which consists almost
+/// \brief Implements the TargetLoweringX8664 class, which consists almost
/// entirely of the lowering sequence for each high-level instruction.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringX8664.h b/src/IceTargetLoweringX8664.h
index b26db59..6169dd2 100644
--- a/src/IceTargetLoweringX8664.h
+++ b/src/IceTargetLoweringX8664.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the TargetLoweringX8664 class, which implements the
+/// \brief Declares the TargetLoweringX8664 class, which implements the
/// TargetLowering interface for the X86 64-bit architecture.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringX8664Traits.h b/src/IceTargetLoweringX8664Traits.h
index e7aa3a2..d0ce225 100644
--- a/src/IceTargetLoweringX8664Traits.h
+++ b/src/IceTargetLoweringX8664Traits.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the X8664 Target Lowering Traits.
+/// \brief Declares the X8664 Target Lowering Traits.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringX86Base.h b/src/IceTargetLoweringX86Base.h
index b3227ec..e2530ed 100644
--- a/src/IceTargetLoweringX86Base.h
+++ b/src/IceTargetLoweringX86Base.h
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the TargetLoweringX86 template class, which implements
-/// the TargetLowering base interface for the x86 architecture.
+/// \brief Declares the TargetLoweringX86 template class, which implements the
+/// TargetLowering base interface for the x86 architecture.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringX86BaseImpl.h b/src/IceTargetLoweringX86BaseImpl.h
index f3246ef..1818f02 100644
--- a/src/IceTargetLoweringX86BaseImpl.h
+++ b/src/IceTargetLoweringX86BaseImpl.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the TargetLoweringX86Base class, which consists almost
+/// \brief Implements the TargetLoweringX86Base class, which consists almost
/// entirely of the lowering sequence for each high-level instruction.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTargetLoweringX86RegClass.h b/src/IceTargetLoweringX86RegClass.h
index 35ae316..5ffb975 100644
--- a/src/IceTargetLoweringX86RegClass.h
+++ b/src/IceTargetLoweringX86RegClass.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the X86 register class extensions.
+/// \brief Declares the X86 register class extensions.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceThreading.cpp b/src/IceThreading.cpp
index 153abff..f186d97 100644
--- a/src/IceThreading.cpp
+++ b/src/IceThreading.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines threading-related functions.
+/// \brief Defines threading-related functions.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceThreading.h b/src/IceThreading.h
index b0bcc01..ecc350e 100644
--- a/src/IceThreading.h
+++ b/src/IceThreading.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares threading-related functions.
+/// \brief Declares threading-related functions.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTimerTree.cpp b/src/IceTimerTree.cpp
index bcf8eaf..e9b5841 100644
--- a/src/IceTimerTree.cpp
+++ b/src/IceTimerTree.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines the TimerTree class, which tracks flat and cumulative
+/// \brief Defines the TimerTree class, which tracks flat and cumulative
/// execution time collection of call chains.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTimerTree.h b/src/IceTimerTree.h
index 796ce8c..fb21f84 100644
--- a/src/IceTimerTree.h
+++ b/src/IceTimerTree.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the TimerTree class, which allows flat and cumulative
+/// \brief Declares the TimerTree class, which allows flat and cumulative
/// execution time collection of call chains.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTranslator.cpp b/src/IceTranslator.cpp
index 68f2b1f..01fb537 100644
--- a/src/IceTranslator.cpp
+++ b/src/IceTranslator.cpp
@@ -8,8 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines the general driver class for translating ICE to machine
-/// code.
+/// \brief Defines the general driver class for translating ICE to machine code.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTranslator.h b/src/IceTranslator.h
index 415965a..1ecd998 100644
--- a/src/IceTranslator.h
+++ b/src/IceTranslator.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the general driver class for translating ICE to machine
+/// \brief Declares the general driver class for translating ICE to machine
/// code.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTypeConverter.cpp b/src/IceTypeConverter.cpp
index ec9e37b..e0c631c 100644
--- a/src/IceTypeConverter.cpp
+++ b/src/IceTypeConverter.cpp
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements how to convert LLVM types to ICE types, and ICE types
-/// to LLVM types.
+/// \brief Implements how to convert LLVM types to ICE types, and ICE types to
+/// LLVM types.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTypeConverter.h b/src/IceTypeConverter.h
index c61423c..6b4c028 100644
--- a/src/IceTypeConverter.h
+++ b/src/IceTypeConverter.h
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines how to convert LLVM types to ICE types, and ICE types to
-/// LLVM types.
+/// \brief Defines how to convert LLVM types to ICE types, and ICE types to LLVM
+/// types.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTypes.cpp b/src/IceTypes.cpp
index d51d0ba..2614d74 100644
--- a/src/IceTypes.cpp
+++ b/src/IceTypes.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines a few attributes of Subzero primitive types.
+/// \brief Defines a few attributes of Subzero primitive types.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceTypes.h b/src/IceTypes.h
index 380a613..a87cf8b 100644
--- a/src/IceTypes.h
+++ b/src/IceTypes.h
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares a few properties of the primitive types allowed in
-/// Subzero. Every Subzero source file is expected to include IceTypes.h.
+/// \brief Declares a few properties of the primitive types allowed in Subzero.
+/// Every Subzero source file is expected to include IceTypes.h.
///
//===----------------------------------------------------------------------===//
diff --git a/src/IceUtils.h b/src/IceUtils.h
index 0080a11..6bdd95e 100644
--- a/src/IceUtils.h
+++ b/src/IceUtils.h
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares some utility functions.
+/// \brief Defines some utility functions.
///
//===----------------------------------------------------------------------===//
diff --git a/src/PNaClTranslator.cpp b/src/PNaClTranslator.cpp
index d5fac3d..0f40df5 100644
--- a/src/PNaClTranslator.cpp
+++ b/src/PNaClTranslator.cpp
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file implements the PNaCl bitcode file to Ice, to machine code
-/// translator.
+/// \brief Implements the interface for translation from PNaCl bitcode files to
+/// ICE to machine code.
///
//===----------------------------------------------------------------------===//
diff --git a/src/PNaClTranslator.h b/src/PNaClTranslator.h
index 8a045ad..2083d41 100644
--- a/src/PNaClTranslator.h
+++ b/src/PNaClTranslator.h
@@ -8,8 +8,8 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file declares the PNaCl bitcode file to ICE, to machine code
-/// translator.
+/// \brief Declares the interface for translation from PNaCl bitcode files to
+/// ICE to machine code.
///
//===----------------------------------------------------------------------===//
diff --git a/src/main.cpp b/src/main.cpp
index fa5bb06..952db7b 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -8,7 +8,7 @@
//===----------------------------------------------------------------------===//
///
/// \file
-/// This file defines the entry point for translating PNaCl bitcode into native
+/// \brief Defines the entry point for translating PNaCl bitcode into native
/// code.
///
//===----------------------------------------------------------------------===//