Documentation cleanup: reformatting/fixing up file comments so that they have

\file and \brief markup and appear in Doxygen's summaries (and eventually at
http://clang.llvm.org/doxygen/files.html).  Fixed up another couple of minor
glitches in the docs at the same time.


git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@159517 91177308-0d34-0410-b5e6-96231b3b80d8

include/clang/Basic/ABI.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// These enums/classes describe ABI related information about constructors,
-// destructors and thunks.
-//
+///
+/// \file
+/// \brief Enums/classes describing ABI related information about constructors,
+/// destructors and thunks.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef CLANG_BASIC_ABI_H

include/clang/Basic/AddressSpaces.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file provides definitions for the various language-specific address
-//  spaces.
-//
+///
+/// \file
+/// \brief Provides definitions for the various language-specific address
+///  spaces.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_ADDRESSSPACES_H

include/clang/Basic/AllDiagnostics.h

@@ -6,10 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file includes all the separate Diagnostic headers & some related
-//  helpers.
-//
+///
+/// \file
+/// \brief Includes all the separate Diagnostic headers & some related helpers.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_ALL_DIAGNOSTICS_H

include/clang/Basic/AttrKinds.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the attr::Kind enum
-//
+///
+/// \file
+/// \brief Defines the clang::attr::Kind enum.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_ATTRKINDS_H

include/clang/Basic/Builtins.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines enum values for all the target-independent builtin
-// functions.
-//
+///
+/// \file
+/// \brief Defines enum values for all the target-independent builtin
+/// functions.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_BUILTINS_H

include/clang/Basic/Diagnostic.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the Diagnostic-related interfaces.
-//
+///
+/// \file
+/// \brief Defines the Diagnostic-related interfaces.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_DIAGNOSTIC_H

include/clang/Basic/DiagnosticIDs.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the Diagnostic IDs-related interfaces.
-//
+///
+/// \file
+/// \brief Defines the Diagnostic IDs-related interfaces.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_DIAGNOSTICIDS_H

include/clang/Basic/ExceptionSpecificationType.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines the ExceptionSpecificationType enumeration and various
-// utility functions.
-//
+///
+/// \file
+/// \brief Defines the ExceptionSpecificationType enumeration and various
+/// utility functions.
+///
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_BASIC_EXCEPTIONSPECIFICATIONTYPE_H
 #define LLVM_CLANG_BASIC_EXCEPTIONSPECIFICATIONTYPE_H

include/clang/Basic/ExpressionTraits.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines enumerations for expression traits intrinsics.
-//
+///
+/// \file
+/// \brief Defines enumerations for expression traits intrinsics.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_EXPRESSIONTRAITS_H

include/clang/Basic/FileManager.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the FileManager interface.
-//
+///
+/// \file
+/// \brief Defines the clang::FileManager interface and associated types.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_FILEMANAGER_H

include/clang/Basic/FileSystemOptions.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the FileSystemOptions interface.
-//
+///
+/// \file
+/// \brief Defines the clang::FileSystemOptions interface.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_FILESYSTEMOPTIONS_H

include/clang/Basic/FileSystemStatCache.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the FileSystemStatCache interface.
-//
+///
+/// \file
+/// \brief Defines the FileSystemStatCache interface.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_FILESYSTEMSTATCACHE_H

include/clang/Basic/IdentifierTable.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines the IdentifierInfo, IdentifierTable, and Selector
-// interfaces.
-//
+///
+/// \file
+/// \brief Defines the clang::IdentifierInfo, clang::IdentifierTable, and
+/// clang::Selector interfaces.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_IDENTIFIERTABLE_H

include/clang/Basic/LLVM.h

@@ -7,9 +7,10 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// This file forward declares and imports various common LLVM datatypes that
-// clang wants to use unqualified.
-//
+/// \file
+/// \brief Forward declares and imports various common LLVM datatypes that
+/// clang wants to use unqualified.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef CLANG_BASIC_LLVM_H

include/clang/Basic/Lambda.h

@@ -6,9 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines several types used to describe C++ lambda
-// expressions that are shared between the parser and AST.
+///
+/// \file
+/// \brief  Defines several types used to describe C++ lambda expressions
+/// that are shared between the parser and AST.
+///
 //===----------------------------------------------------------------------===//
 
 

include/clang/Basic/LangOptions.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the LangOptions interface.
-//
+///
+/// \file
+/// \brief Defines the clang::LangOptions interface.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_LANGOPTIONS_H

include/clang/Basic/Linkage.h

@@ -6,10 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines the Linkage enumeration and various utility
-// functions.
-//
+///
+/// \file
+/// \brief Defines the Linkage enumeration and various utility functions.
+///
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_BASIC_LINKAGE_H
 #define LLVM_CLANG_BASIC_LINKAGE_H

include/clang/Basic/MacroBuilder.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the MacroBuilder utility class.
-//
+///
+/// \file
+/// \brief Defines the clang::MacroBuilder utility class.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_MACROBUILDER_H

include/clang/Basic/Module.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines the Module class, which describes a module in the source
-// code.
-//
+///
+/// \file
+/// \brief Defines the clang::Module class, which describes a module in the
+/// source code.
+///
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_BASIC_MODULE_H
 #define LLVM_CLANG_BASIC_MODULE_H
@@ -137,7 +138,7 @@ public:
   llvm::SmallVector<ExportDecl, 2> Exports;
   
   /// \brief Describes an exported module that has not yet been resolved
-  /// (perhaps because tASThe module it refers to has not yet been loaded).
+  /// (perhaps because the module it refers to has not yet been loaded).
   struct UnresolvedExportDecl {
     /// \brief The location of the 'export' keyword in the module map file.
     SourceLocation ExportLoc;

include/clang/Basic/ObjCRuntime.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines types useful for describing an Objective-C runtime.
-//
+///
+/// \file
+/// \brief Defines types useful for describing an Objective-C runtime.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_OBJCRUNTIME_H

include/clang/Basic/OnDiskHashTable.h

@@ -6,10 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines facilities for reading and writing on-disk hash
-//  tables.
-//
+///
+/// \file
+/// \brief Defines facilities for reading and writing on-disk hash tables.
+///
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_BASIC_ON_DISK_HASH_TABLE_H
 #define LLVM_CLANG_BASIC_ON_DISK_HASH_TABLE_H

include/clang/Basic/OpenCL.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines some OpenCL-specific enums.
-//
+///
+/// \file
+/// \brief Defines some OpenCL-specific enums.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_OPENCL_H

include/clang/Basic/OperatorKinds.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines C++ overloaded operators.
-//
+///
+/// \file
+/// \brief Defines an enumeration for C++ overloaded operators.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_OPERATOR_KINDS_H

include/clang/Basic/PartialDiagnostic.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file implements a partial diagnostic that can be emitted anwyhere
-//  in a DiagnosticBuilder stream.
-//
+///
+/// \file
+/// \brief Implements a partial diagnostic that can be emitted anwyhere
+/// in a DiagnosticBuilder stream.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_PARTIALDIAGNOSTIC_H

include/clang/Basic/PrettyStackTrace.h

@@ -6,11 +6,12 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines the PrettyStackTraceEntry class, which is used to make
-// crashes give more contextual information about what the program was doing
-// when it crashed.
-//
+///
+/// \file
+/// \brief Defines the PrettyStackTraceEntry class, which is used to make
+/// crashes give more contextual information about what the program was doing
+/// when it crashed.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef CLANG_BASIC_PRETTYSTACKTRACE_H

include/clang/Basic/SourceLocation.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the SourceLocation class.
-//
+///
+/// \file
+/// \brief Defines the clang::SourceLocation class and associated facilities.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_SOURCELOCATION_H

include/clang/Basic/SourceManager.h

@@ -7,9 +7,10 @@
 //
 //===----------------------------------------------------------------------===//
 ///
-/// \file Defines the SourceManager interface.
+/// \file
+/// \brief Defines the SourceManager interface.
 ///
-/// There are three different types of locations in a file\: a spelling
+/// There are three different types of locations in a file: a spelling
 /// location, an expansion location, and a presumed location.
 ///
 /// Given an example of:
@@ -19,7 +20,7 @@
 ///
 /// and then later on a use of min:
 /// \code
-/// \#line 17
+/// #line 17
 /// return min(a, b);
 /// \endcode
 ///

include/clang/Basic/SourceManagerInternals.h

@@ -6,10 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the implementation details of the SourceManager
-//  class.
-//
+///
+/// \file
+/// \brief Defines implementation details of the clang::SourceManager class.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_SOURCEMANAGER_INTERNALS_H

include/clang/Basic/Specifiers.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines various enumerations that describe declaration and
-// type specifiers.
-//
+///
+/// \file
+/// \brief Defines various enumerations that describe declaration and
+/// type specifiers.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_SPECIFIERS_H

include/clang/Basic/TargetBuiltins.h

@@ -6,6 +6,12 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Enumerates target-specific builtins in their own namespaces within
+/// namespace ::clang.
+///
+//===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_TARGET_BUILTINS_H
 #define LLVM_CLANG_BASIC_TARGET_BUILTINS_H

include/clang/Basic/TargetInfo.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the TargetInfo interface.
-//
+///
+/// \file
+/// \brief Defines the clang::TargetInfo interface.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_TARGETINFO_H

include/clang/Basic/TargetOptions.h

@@ -6,6 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Defines the clang::TargetOptions class.
+///
+//===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_FRONTEND_TARGETOPTIONS_H
 #define LLVM_CLANG_FRONTEND_TARGETOPTIONS_H

include/clang/Basic/TemplateKinds.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the TemplateNameKind enum.
-//
+///
+/// \file
+/// \brief Defines the clang::TemplateNameKind enum.
+///
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_TEMPLATEKINDS_H
 #define LLVM_CLANG_TEMPLATEKINDS_H

include/clang/Basic/TokenKinds.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the TokenKind enum and support functions.
-//
+///
+/// \file
+/// \brief Defines the clang::TokenKind enum and support functions.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_TOKENKINDS_H

include/clang/Basic/TypeTraits.h

@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines enumerations for the type traits support.
-//
+///
+/// \file
+/// \brief Defines enumerations for the type traits support.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_TYPETRAITS_H

include/clang/Basic/Version.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This header defines version macros and version-related utility functions
-// for Clang.
-//
+///
+/// \file
+/// \brief Defines version macros and version-related utility functions
+/// for Clang.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_VERSION_H

include/clang/Basic/VersionTuple.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This header defines the VersionTuple class, which represents a version in
-// the form major[.minor[.subminor]].
-//
+///
+/// \file
+/// \brief Defines the clang::VersionTuple class, which represents a version in
+/// the form major[.minor[.subminor]].
+///
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_BASIC_VERSIONTUPLE_H
 #define LLVM_CLANG_BASIC_VERSIONTUPLE_H

include/clang/Basic/Visibility.h

@@ -6,10 +6,11 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file defines the Visibility enumeration and various utility
-// functions.
-//
+///
+/// \file
+/// \brief Defines the clang::Visibility enumeration and various utility
+/// functions.
+///
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_BASIC_VISIBILITY_H
 #define LLVM_CLANG_BASIC_VISIBILITY_H