[docs] Fix doxygen comments wrongly attached to the llvm namespace

[nicolas17]

Summary

Looking at the Doxygen-generated documentation for the llvm namespace
currently shows all sorts of random comments from different parts of the
codebase. These are mostly caused by:

• File doc comments that aren't marked with \file, so they're attached to the next declaration, which is usually "namespace llvm {".
• Class doc comments placed before the namespace rather than before the class.
• Code comments before the namespace that (in my opinion) shouldn't be extracted by doxygen at all.

This commit fixes these comments. The generated doxygen documentation now
has proper docs for several classes and files, and the docs for the llvm
and llvm::detail namespaces are now empty.

[mizvekov]

In general LGTM, once you address the couple of points I raised, and address the relevant linter issues.

llvm/include/llvm/ADT/STLExtras.h

93

I think you should just update the comment to describe is_detected, instead of talking about 'utilities' in general.

llvm/include/llvm/CodeGen/Passes.h

89

Since clang-format is complaining this line is too long anyway, I think you could just remove the redundant mention of 'pass'.

[nicolas17]

Rebase and apply suggestions

Update the comment for is_detected, and fix some linter complaints.

[nicolas17]

I don't have commit access, please push this for me.

llvm/include/llvm/CodeGen/Passes.h

89

We should actually remove the redundant "MachineDominanaceFrontier" from the comment (I just noticed this one isn't even spelled correctly!), but then I would need to do it to the others, and that certainly belongs in a different commit...

llvm/include/llvm/ADT/STLExtras.h

using type =
       typename std::add_pointer<typename std::add_const<T>::type>::type;
 };
 
 template <typename T> struct make_const_ref {
   using type = typename std::add_lvalue_reference<
       typename std::add_const<T>::type>::type;
 };
 
-/// Utilities for detecting if a given trait holds for some set of arguments
-/// 'Args'. For example, the given trait could be used to detect if a given type
-/// has a copy assignment operator:
-///   template<class T>
-///   using has_copy_assign_t = decltype(std::declval<T&>()
-///                                                 = std::declval<const T&>());
-///   bool fooHasCopyAssign = is_detected<has_copy_assign_t, FooClass>::value;
 namespace detail {
 template <typename...> using void_t = void;
 template <class, template <class...> class Op, class... Args> struct detector {
   using value_t = std::false_type;
 };
 template <template <class...> class Op, class... Args>
 struct detector<void_t<Op<Args...>>, Op, Args...> {
   using value_t = std::true_type;
 };
 } // end namespace detail
 
+/// Detects if a given trait holds for some set of arguments 'Args'.
+/// For example, the given trait could be used to detect if a given type
+/// has a copy assignment operator:
+///   template<class T>
+///   using has_copy_assign_t = decltype(std::declval<T&>()
+///                                                 = std::declval<const T&>());
+///   bool fooHasCopyAssign = is_detected<has_copy_assign_t, FooClass>::value;
 template <template <class...> class Op, class... Args>
 using is_detected = typename detail::detector<void, Op, Args...>::value_t;
 
-/// Check if a Callable type can be invoked with the given set of arg types.
 namespace detail {
 template <typename Callable, typename... Args>
 using is_invocable =
     decltype(std::declval<Callable &>()(std::declval<Args>()...));
 } // namespace detail
 
+/// Check if a Callable type can be invoked with the given set of arg types.
 template <typename Callable, typename... Args>
 using is_invocable = is_detected<detail::is_invocable, Callable, Args...>;
 
 /// This class provides various trait information about a callable object.
 ///   * To access the number of arguments: Traits::num_args
 ///   * To access the type of an argument: Traits::arg_t<Index>
 ///   * To access the type of the result:  Traits::result_t
 template <typename T, bool isClass = std::is_class<T>::value>

llvm/include/llvm/Analysis/ValueLattice.h

 #include "llvm/IR/ConstantRange.h"
 #include "llvm/IR/Constants.h"
 #include "llvm/IR/Instructions.h"
 //
 //===----------------------------------------------------------------------===//
 //                               ValueLatticeElement
 //===----------------------------------------------------------------------===//
 
+namespace llvm {
+
 /// This class represents lattice values for constants.
 ///
 /// FIXME: This is basically just for bringup, this can be made a lot more rich
 /// in the future.
 ///
-
-namespace llvm {
 class ValueLatticeElement {
   enum ValueLatticeElementTy {
     /// This Value has no known value yet.  As a result, this implies the
     /// producing instruction is dead.  Caution: We use this as the starting
     /// state in our local meet rules.  In this usage, it's taken to mean
     /// "nothing known yet".
     /// Transition to any other state allowed.
     unknown,

llvm/include/llvm/BinaryFormat/MsgPackDocument.h

 //===-- MsgPackDocument.h - MsgPack Document --------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-///
+/// \file
 /// This file declares a class that exposes a simple in-memory representation
 /// of a document of MsgPack objects, that can be read from MsgPack, written to
 /// MsgPack, and inspected and modified in memory. This is intended to be a
 /// lighter-weight (in terms of memory allocations) replacement for
 /// MsgPackTypes.
 ///
 //===----------------------------------------------------------------------===//
 

llvm/include/llvm/CodeGen/AccelTable.h

 //==- include/llvm/CodeGen/AccelTable.h - Accelerator Tables -----*- C++ -*-==//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
-// This file contains support for writing accelerator tables.
-//
+/// \file
+/// This file contains support for writing accelerator tables.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CODEGEN_ACCELTABLE_H
 #define LLVM_CODEGEN_ACCELTABLE_H
 
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/ADT/StringMap.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/BinaryFormat/Dwarf.h"
 #include "llvm/CodeGen/DIE.h"
 #include "llvm/CodeGen/DwarfStringPoolEntry.h"
 #include "llvm/MC/MCSymbol.h"
 #include "llvm/Support/Allocator.h"
 #include "llvm/Support/DJB.h"
 #include "llvm/Support/Debug.h"
 #include "llvm/Support/Format.h"
 #include "llvm/Support/raw_ostream.h"
 #include <cstddef>
 #include <cstdint>
 #include <vector>
 
+/// \file
 /// The DWARF and Apple accelerator tables are an indirect hash table optimized
 /// for null lookup rather than access to known data. The Apple accelerator
 /// tables are a precursor of the newer DWARF v5 accelerator tables. Both
 /// formats share common design ideas.
 ///
 /// The Apple accelerator table are output into an on-disk format that looks
 /// like this:
 ///

llvm/include/llvm/CodeGen/GlobalISel/CSEInfo.h

 //===- llvm/CodeGen/GlobalISel/CSEInfo.h ------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// Provides analysis for continuously CSEing during GISel passes.
-//
+///
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CODEGEN_GLOBALISEL_CSEINFO_H
 #define LLVM_CODEGEN_GLOBALISEL_CSEINFO_H
 
 #include "llvm/ADT/FoldingSet.h"
 #include "llvm/CodeGen/CSEConfigBase.h"
 #include "llvm/CodeGen/GlobalISel/GISelChangeObserver.h"
 #include "llvm/CodeGen/GlobalISel/GISelWorkList.h"

llvm/include/llvm/CodeGen/GlobalISel/Combiner.h

 //== ----- llvm/CodeGen/GlobalISel/Combiner.h -------------------*- C++ -*-== //
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// This contains common code to drive combines. Combiner Passes will need to
 /// setup a CombinerInfo and call combineMachineFunction.
-//
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CODEGEN_GLOBALISEL_COMBINER_H
 #define LLVM_CODEGEN_GLOBALISEL_COMBINER_H
 
 #include "llvm/CodeGen/GlobalISel/MachineIRBuilder.h"
 #include "llvm/CodeGen/MachineFunctionPass.h"
 

llvm/include/llvm/CodeGen/GlobalISel/CombinerHelper.h

 //===-- llvm/CodeGen/GlobalISel/CombinerHelper.h --------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===--------------------------------------------------------------------===//
-//
+/// \file
 /// This contains common combine transformations that may be used in a combine
 /// pass,or by the target elsewhere.
 /// Targets can pick individual opcode transformations from the helper or use
 /// tryCombine which invokes all transformations. All of the transformations
 /// return true if the MachineInstruction changed and false otherwise.
-//
+///
 //===--------------------------------------------------------------------===//
 
 #ifndef LLVM_CODEGEN_GLOBALISEL_COMBINERHELPER_H
 #define LLVM_CODEGEN_GLOBALISEL_COMBINERHELPER_H
 
 #include "llvm/ADT/APFloat.h"
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/CodeGen/LowLevelType.h"

llvm/include/llvm/CodeGen/GlobalISel/CombinerInfo.h

 //===- llvm/CodeGen/GlobalISel/CombinerInfo.h ------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// Interface for Targets to specify which operations are combined how and when.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CODEGEN_GLOBALISEL_COMBINERINFO_H
 #define LLVM_CODEGEN_GLOBALISEL_COMBINERINFO_H
 
 #include <cassert>

llvm/include/llvm/CodeGen/GlobalISel/GISelChangeObserver.h

 //===----- llvm/CodeGen/GlobalISel/GISelChangeObserver.h --------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// This contains common code to allow clients to notify changes to machine
 /// instr.
-//
+///
 //===----------------------------------------------------------------------===//
+
 #ifndef LLVM_CODEGEN_GLOBALISEL_GISELCHANGEOBSERVER_H
 #define LLVM_CODEGEN_GLOBALISEL_GISELCHANGEOBSERVER_H
 
 #include "llvm/ADT/SmallPtrSet.h"
 #include "llvm/CodeGen/MachineFunction.h"
 
 namespace llvm {
 class MachineInstr;

llvm/include/llvm/CodeGen/GlobalISel/GISelKnownBits.h

 //===- llvm/CodeGen/GlobalISel/GISelKnownBits.h ---------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// Provides analysis for querying information about KnownBits during GISel
 /// passes.
-//
+///
 //===----------------------------------------------------------------------===//
+
 #ifndef LLVM_CODEGEN_GLOBALISEL_GISELKNOWNBITS_H
 #define LLVM_CODEGEN_GLOBALISEL_GISELKNOWNBITS_H
 
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/CodeGen/GlobalISel/GISelChangeObserver.h"
 #include "llvm/CodeGen/MachineFunctionPass.h"
 #include "llvm/CodeGen/Register.h"
 #include "llvm/InitializePasses.h"

llvm/include/llvm/CodeGen/GlobalISel/LegalizerInfo.h

 //===- llvm/CodeGen/GlobalISel/LegalizerInfo.h ------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// Interface for Targets to specify which operations they can successfully
 /// select and how the others should be expanded most efficiently.
-//
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CODEGEN_GLOBALISEL_LEGALIZERINFO_H
 #define LLVM_CODEGEN_GLOBALISEL_LEGALIZERINFO_H
 
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/None.h"
 #include "llvm/ADT/Optional.h"

llvm/include/llvm/CodeGen/GlobalISel/LostDebugLocObserver.h

 //===----- llvm/CodeGen/GlobalISel/LostDebugLocObserver.h -------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// Tracks DebugLocs between checkpoints and verifies that they are transferred.
-//
+///
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CODEGEN_GLOBALISEL_LOSTDEBUGLOCOBSERVER_H
 #define LLVM_CODEGEN_GLOBALISEL_LOSTDEBUGLOCOBSERVER_H
 
 #include "llvm/ADT/SmallSet.h"
 #include "llvm/CodeGen/GlobalISel/GISelChangeObserver.h"
 
 namespace llvm {

llvm/include/llvm/CodeGen/GlobalISel/MIPatternMatch.h

 //==------ llvm/CodeGen/GlobalISel/MIPatternMatch.h -------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// Contains matchers for matching SSA Machine Instructions.
-//
+///
 //===----------------------------------------------------------------------===//
+
 #ifndef LLVM_CODEGEN_GLOBALISEL_MIPATTERNMATCH_H
 #define LLVM_CODEGEN_GLOBALISEL_MIPATTERNMATCH_H
 
 #include "llvm/CodeGen/GlobalISel/Utils.h"
 #include "llvm/CodeGen/MachineRegisterInfo.h"
 #include "llvm/IR/InstrTypes.h"
 
 namespace llvm {

llvm/include/llvm/CodeGen/GlobalISel/RegBankSelect.h

 //=- llvm/CodeGen/GlobalISel/RegBankSelect.h - Reg Bank Selector --*- C++ -*-=//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
-/// \file This file describes the interface of the MachineFunctionPass
+/// \file
+/// This file describes the interface of the MachineFunctionPass
 /// responsible for assigning the generic virtual registers to register bank.
-
+///
 /// By default, the reg bank selector relies on local decisions to
 /// assign the register bank. In other words, it looks at one instruction
 /// at a time to decide where the operand of that instruction should live.
 ///
 /// At higher optimization level, we could imagine that the reg bank selector
 /// would use more global analysis and do crazier thing like duplicating
 /// instructions and so on. This is future work.
 ///

llvm/include/llvm/CodeGen/LowLevelType.h

 //== llvm/CodeGen/LowLevelType.h ------------------------------- -*- C++ -*-==//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// Implement a low-level type suitable for MachineInstr level instruction
 /// selection.
 ///
 /// This provides the CodeGen aspects of LowLevelType, such as Type conversion.
-//
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CODEGEN_LOWLEVELTYPE_H
 #define LLVM_CODEGEN_LOWLEVELTYPE_H
 
 #include "llvm/Support/LowLevelTypeImpl.h"
 #include "llvm/Support/MachineValueType.h"
 

llvm/include/llvm/CodeGen/Passes.h

 class ModulePass;
 class Pass;
 class TargetMachine;
 class TargetRegisterClass;
 class raw_ostream;
 
 } // End llvm namespace
 
-/// List of target independent CodeGen pass IDs.
+// List of target independent CodeGen pass IDs.
 namespace llvm {
   FunctionPass *createAtomicExpandPass();
 
   /// createUnreachableBlockEliminationPass - The LLVM code generator does not
   /// work well with unreachable basic blocks (what live ranges make sense for a
   /// block that cannot be reached?).  As such, a code generator should either
   /// not instruction select unreachable blocks, or run this pass as its
   /// last LLVM modifying pass to clean up blocks that are not reachable from
namespace llvm {
   extern char &AtomicExpandID;
 
   /// MachineLoopInfo - This pass is a loop analysis pass.
   extern char &MachineLoopInfoID;
 
   /// MachineDominators - This pass is a machine dominators analysis pass.
   extern char &MachineDominatorsID;
 
-/// MachineDominanaceFrontier - This pass is a machine dominators analysis pass.
+  /// MachineDominanaceFrontier - This pass is a machine dominators analysis.
   extern char &MachineDominanceFrontierID;
 
   /// MachineRegionInfo - This pass computes SESE regions for machine functions.
   extern char &MachineRegionInfoPassID;
 
   /// EdgeBundles analysis - Bundle machine CFG edges.
   extern char &EdgeBundlesID;
 

llvm/include/llvm/CodeGen/TargetPassConfig.h

 //===- TargetPassConfig.h - Code Generation pass options --------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// Target-Independent Code Generator Pass Configuration Options pass.
-//
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CODEGEN_TARGETPASSCONFIG_H
 #define LLVM_CODEGEN_TARGETPASSCONFIG_H
 
 #include "llvm/Pass.h"
 #include "llvm/Support/CodeGen.h"
 #include <cassert>

llvm/include/llvm/ExecutionEngine/Orc/SpeculateAnalyses.h

 //===-- SpeculateAnalyses.h  --*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-// \file
+/// \file
 /// Contains the Analyses and Result Interpretation to select likely functions
 /// to Speculatively compile before they are called. [Purely Experimentation]
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_EXECUTIONENGINE_ORC_SPECULATEANALYSES_H
 #define LLVM_EXECUTIONENGINE_ORC_SPECULATEANALYSES_H
 
 #include "llvm/Analysis/BranchProbabilityInfo.h"

llvm/include/llvm/IR/GlobalIFunc.h

 //===-------- llvm/GlobalIFunc.h - GlobalIFunc class ------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 ///
-/// \brief
+/// \file
 /// This file contains the declaration of the GlobalIFunc class, which
 /// represents a single indirect function in the IR. Indirect function uses
 /// ELF symbol type extension to mark that the address of a declaration should
 /// be resolved at runtime by calling a resolver function.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_IR_GLOBALIFUNC_H

llvm/include/llvm/IR/PassManagerImpl.h

 //===- PassManagerImpl.h - Pass management infrastructure -------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-///
+/// \file
 /// Provides implementations for PassManager and AnalysisManager template
 /// methods. These classes should be explicitly instantiated for any IR unit,
 /// and files doing the explicit instantiation should include this header.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_IR_PASSMANAGERIMPL_H
 #define LLVM_IR_PASSMANAGERIMPL_H

llvm/include/llvm/IR/PassManagerInternal.h

 #include <utility>
 
 namespace llvm {
 
 template <typename IRUnitT> class AllAnalysesOn;
 template <typename IRUnitT, typename... ExtraArgTs> class AnalysisManager;
 class PreservedAnalyses;
 
-/// Implementation details of the pass manager interfaces.
+// Implementation details of the pass manager interfaces.
 namespace detail {
 
 /// Template for the abstract base class used to dispatch
 /// polymorphically over pass objects.
 template <typename IRUnitT, typename AnalysisManagerT, typename... ExtraArgTs>
 struct PassConcept {
   // Boiler plate necessary for the container of derived classes.
   virtual ~PassConcept() = default;

llvm/include/llvm/InterfaceStub/ELFObjHandler.h

 //===- ELFObjHandler.h ------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===-----------------------------------------------------------------------===/
-///
+/// \file
 /// This supports reading and writing of elf dynamic shared objects.
 ///
 //===-----------------------------------------------------------------------===/
 
 #ifndef LLVM_INTERFACESTUB_ELFOBJHANDLER_H
 #define LLVM_INTERFACESTUB_ELFOBJHANDLER_H
 
 #include "llvm/InterfaceStub/ELFStub.h"

llvm/include/llvm/Support/BinaryStreamArray.h

 //===- BinaryStreamArray.h - Array backed by an arbitrary stream *- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
+///
+/// \file
+/// Lightweight arrays that are backed by an arbitrary BinaryStream.  This file
+/// provides two different array implementations.
+///
+///     VarStreamArray - Arrays of variable length records.  The user specifies
+///       an Extractor type that can extract a record from a given offset and
+///       return the number of bytes consumed by the record.
+///
+///     FixedStreamArray - Arrays of fixed length records.  This is similar in
+///       spirit to ArrayRef<T>, but since it is backed by a BinaryStream, the
+///       elements of the array need not be laid out in contiguous memory.
+///
 
 #ifndef LLVM_SUPPORT_BINARYSTREAMARRAY_H
 #define LLVM_SUPPORT_BINARYSTREAMARRAY_H
 
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/iterator.h"
 #include "llvm/Support/Alignment.h"
 #include "llvm/Support/BinaryStreamRef.h"
 #include "llvm/Support/Error.h"
 #include <cassert>
 #include <cstdint>
 
-/// Lightweight arrays that are backed by an arbitrary BinaryStream.  This file
-/// provides two different array implementations.
-///
-///     VarStreamArray - Arrays of variable length records.  The user specifies
-///       an Extractor type that can extract a record from a given offset and
-///       return the number of bytes consumed by the record.
-///
-///     FixedStreamArray - Arrays of fixed length records.  This is similar in
-///       spirit to ArrayRef<T>, but since it is backed by a BinaryStream, the
-///       elements of the array need not be laid out in contiguous memory.
 namespace llvm {
 
 /// VarStreamArrayExtractor is intended to be specialized to provide customized
 /// extraction logic.  On input it receives a BinaryStreamRef pointing to the
 /// beginning of the next record, but where the length of the record is not yet
 /// known.  Upon completion, it should return an appropriate Error instance if
 /// a record could not be extracted, or if one could be extracted it should
 /// return success and set Len to the number of bytes this record occupied in

llvm/include/llvm/Support/Chrono.h

 ///
 /// If no options are given, the default format is "%Y-%m-%d %H:%M:%S.%N".
 template <>
 struct format_provider<sys::TimePoint<>> {
   static void format(const sys::TimePoint<> &TP, llvm::raw_ostream &OS,
                      StringRef Style);
 };
 
+namespace detail {
+template <typename Period> struct unit { static const char value[]; };
+template <typename Period> const char unit<Period>::value[] = "";
+
+template <> struct unit<std::ratio<3600>> { static const char value[]; };
+template <> struct unit<std::ratio<60>> { static const char value[]; };
+template <> struct unit<std::ratio<1>> { static const char value[]; };
+template <> struct unit<std::milli> { static const char value[]; };
+template <> struct unit<std::micro> { static const char value[]; };
+template <> struct unit<std::nano> { static const char value[]; };
+} // namespace detail
+
 /// Implementation of format_provider<T> for duration types.
 ///
-/// The options string of a duration  type has the grammar:
+/// The options string of a duration type has the grammar:
 ///
 ///   duration_options  ::= [unit][show_unit [number_options]]
 ///   unit              ::= `h`|`m`|`s`|`ms|`us`|`ns`
 ///   show_unit         ::= `+` | `-`
 ///   number_options    ::= options string for a integral or floating point type
 ///
 ///   Examples
 ///   =================================
 ///   |  options  | Input | Output    |
 ///   =================================
 ///   | ""        | 1s    | 1 s       |
 ///   | "ms"      | 1s    | 1000 ms   |
 ///   | "ms-"     | 1s    | 1000      |
 ///   | "ms-n"    | 1s    | 1,000     |
 ///   | ""        | 1.0s  | 1.00 s    |
 ///   =================================
 ///
 ///  If the unit of the duration type is not one of the units specified above,
 ///  it is still possible to format it, provided you explicitly request a
 ///  display unit or you request that the unit is not displayed.
 
-namespace detail {
-template <typename Period> struct unit { static const char value[]; };
-template <typename Period> const char unit<Period>::value[] = "";
-
-template <> struct unit<std::ratio<3600>> { static const char value[]; };
-template <> struct unit<std::ratio<60>> { static const char value[]; };
-template <> struct unit<std::ratio<1>> { static const char value[]; };
-template <> struct unit<std::milli> { static const char value[]; };
-template <> struct unit<std::micro> { static const char value[]; };
-template <> struct unit<std::nano> { static const char value[]; };
-} // namespace detail
-
 template <typename Rep, typename Period>
 struct format_provider<std::chrono::duration<Rep, Period>> {
 private:
   typedef std::chrono::duration<Rep, Period> Dur;
   typedef std::conditional_t<std::chrono::treat_as_floating_point<Rep>::value,
                              double, intmax_t>
       InternalRep;
 

llvm/include/llvm/Support/LowLevelTypeImpl.h

 //== llvm/Support/LowLevelTypeImpl.h --------------------------- -*- C++ -*-==//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// Implement a low-level type suitable for MachineInstr level instruction
 /// selection.
 ///
 /// For a type attached to a MachineInstr, we only care about 2 details: total
 /// size and the number of vector lanes (if any). Accordingly, there are 4
 /// possible valid type-kinds:
 ///
 ///    * `sN` for scalars and aggregates
 ///    * `<N x sM>` for vectors, which must have at least 2 elements.
 ///    * `pN` for pointers
 ///
 /// Other information required for correct selection is expected to be carried
 /// by the opcode, or non-type flags. For example the distinction between G_ADD
 /// and G_FADD for int/float or fast-math flags.
-//
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_SUPPORT_LOWLEVELTYPEIMPL_H
 #define LLVM_SUPPORT_LOWLEVELTYPEIMPL_H
 
 #include "llvm/ADT/DenseMapInfo.h"
 #include "llvm/Support/Debug.h"
 #include "llvm/Support/MachineValueType.h"

llvm/include/llvm/Support/OptimizedStructLayout.h

 //===-- OptimizedStructLayout.h - Struct layout algorithm ---------*- C++ -*-=//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 ///
+/// \file
 /// This file provides an interface for laying out a sequence of fields
 /// as a struct in a way that attempts to minimizes the total space
 /// requirements of the struct while still satisfying the layout
 /// requirements of the individual fields.  The resulting layout may be
 /// substantially more compact than simply laying out the fields in their
 /// original order.
 ///
 /// Fields may be pre-assigned fixed offsets.  They may also be given sizes
 /// that are not multiples of their alignments.  There is no currently no
 /// way to describe that a field has interior padding that other fields may
 /// be allocated into.
 ///
 /// This algorithm does not claim to be "optimal" for several reasons:
 ///
 /// - First, it does not guarantee that the result is minimal in size.
 ///   There is no known efficient algoorithm to achieve minimality for
-///   unrestricted inputs.  Nonetheless, this algorithm 
+///   unrestricted inputs.  Nonetheless, this algorithm
 ///
 /// - Second, there are other ways that a struct layout could be optimized
 ///   besides space usage, such as locality.  This layout may have a mixed
 ///   impact on locality: less overall memory may be used, but adjacent
 ///   fields in the original array may be moved further from one another.
 ///
 //===----------------------------------------------------------------------===//
 

llvm/lib/CodeGen/EdgeBundles.cpp

for (unsigned i = 0, e = MF->getNumBlockIDs(); i != e; ++i) {
     Blocks[b0].push_back(i);
     if (b1 != b0)
       Blocks[b1].push_back(i);
   }
 
   return false;
 }
 
-/// Specialize WriteGraph, the standard implementation won't work.
 namespace llvm {
 
+/// Specialize WriteGraph, the standard implementation won't work.
 template<>
 raw_ostream &WriteGraph<>(raw_ostream &O, const EdgeBundles &G,
                           bool ShortNames,
                           const Twine &Title) {
   const MachineFunction *MF = G.getMachineFunction();
 
   O << "digraph {\n";
   for (const auto &MBB : *MF) {

llvm/lib/CodeGen/LiveRangeUtils.h

 //===-- LiveRangeUtils.h - Live Range modification utilities ----*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-//
+/// \file
 /// This file contains helper functions to modify live ranges.
-//
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_LIB_CODEGEN_LIVERANGEUTILS_H
 #define LLVM_LIB_CODEGEN_LIVERANGEUTILS_H
 
 #include "llvm/CodeGen/LiveInterval.h"
 
 namespace llvm {

llvm/lib/CodeGen/MachineSSAUpdater.cpp

if (UseMI->isPHI()) {
     NewVR = GetValueAtEndOfBlockInternal(SourceBB);
   } else {
     NewVR = GetValueInMiddleOfBlock(UseMI->getParent());
   }
 
   U.setReg(NewVR);
 }
 
-/// SSAUpdaterTraits<MachineSSAUpdater> - Traits for the SSAUpdaterImpl
-/// template, specialized for MachineSSAUpdater.
 namespace llvm {
 
+/// SSAUpdaterTraits<MachineSSAUpdater> - Traits for the SSAUpdaterImpl
+/// template, specialized for MachineSSAUpdater.
 template<>
 class SSAUpdaterTraits<MachineSSAUpdater> {
 public:
   using BlkT = MachineBasicBlock;
   using ValT = Register;
   using PhiT = MachineInstr;
   using BlkSucc_iterator = MachineBasicBlock::succ_iterator;
 

llvm/lib/Target/Hexagon/HexagonISelDAGToDAG.cpp

 
 //===----------------------------------------------------------------------===//
 // Instruction Selector Implementation
 //===----------------------------------------------------------------------===//
 
 #define GET_DAGISEL_BODY HexagonDAGToDAGISel
 #include "HexagonGenDAGISel.inc"
 
+namespace llvm {
 /// createHexagonISelDag - This pass converts a legalized DAG into a
 /// Hexagon-specific DAG, ready for instruction scheduling.
-///
-namespace llvm {
 FunctionPass *createHexagonISelDag(HexagonTargetMachine &TM,
                                    CodeGenOpt::Level OptLevel) {
   return new HexagonDAGToDAGISel(TM, OptLevel);
 }
 }
 
 void HexagonDAGToDAGISel::SelectIndexedLoad(LoadSDNode *LD, const SDLoc &dl) {
   SDValue Chain = LD->getChain();

llvm/lib/Target/X86/ImmutableGraph.h

 //==========-- ImmutableGraph.h - A fast DAG implementation ---------=========//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
-///
+/// \file
 /// Description: ImmutableGraph is a fast DAG implementation that cannot be
 /// modified, except by creating a new ImmutableGraph. ImmutableGraph is
 /// implemented as two arrays: one containing nodes, and one containing edges.
 /// The advantages to this implementation are two-fold:
 /// 1. Iteration and traversal operations benefit from cache locality.
 /// 2. Operations on sets of nodes/edges are efficient, and representations of
 ///    those sets in memory are compact. For instance, a set of edges is
 ///    implemented as a bit vector, wherein each bit corresponds to one edge in

llvm/lib/Target/X86/X86OptimizeLEAs.cpp

public:
   const MachineOperand *Operands[4];
 
   // Address' displacement operand.
   const MachineOperand *Disp;
 };
 
 } // end anonymous namespace
 
-/// Provide DenseMapInfo for MemOpKey.
 namespace llvm {
 
+/// Provide DenseMapInfo for MemOpKey.
 template <> struct DenseMapInfo<MemOpKey> {
   using PtrInfo = DenseMapInfo<const MachineOperand *>;
 
   static inline MemOpKey getEmptyKey() {
     return MemOpKey(PtrInfo::getEmptyKey(), PtrInfo::getEmptyKey(),
                     PtrInfo::getEmptyKey(), PtrInfo::getEmptyKey(),
                     PtrInfo::getEmptyKey());
   }