[BOLT][NFC] Fix file-description comments

Summary: Fix comments at the start of source files.

(cherry picked from FBD33274597)

bolt/include/bolt/Core/BinaryBasicBlock.h

@@ -1,12 +1,14 @@
-//===--- BinaryBasicBlock.h - Interface for assembly-level basic block ----===//
+//===- bolt/Core/BinaryBasicBlock.h - Low-level basic block -----*- 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
 //
 //===----------------------------------------------------------------------===//
 //
-// Sequence of MC(Plus) instructions. Call/invoke does not terminate the block.
+// Sequence of MC/MCPlus instructions. Call/invoke does not terminate the block.
+// CFI instructions are part of the instruction list with the initial CFI state
+// defined at the beginning of the block.
 //
 //===----------------------------------------------------------------------===//
 

bolt/include/bolt/Core/BinaryContext.h

@@ -1,12 +1,12 @@
-//===--- BinaryContext.h  - Interface for machine-level context -----------===//
+//===- bolt/Core/BinaryContext.h - Low-level context ------------*- 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
 //
 //===----------------------------------------------------------------------===//
 //
-// Context for processing binary executables in files and/or memory.
+// Context for processing binary executable/library files.
 //
 //===----------------------------------------------------------------------===//
 

bolt/include/bolt/Core/BinaryData.h

@@ -1,11 +1,15 @@
-//===--- BinaryData.h  - Representation of section data objects -----------===//
+//===- bolt/Core/BinaryData.h - Objects in a binary file --------*- 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 the declaration of the BinaryData class, which represents
+// an allocatable entity in a binary file, such as a data object, a jump table,
+// or a function.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_CORE_BINARY_DATA_H

bolt/include/bolt/Core/BinaryEmitter.h

@@ -1,11 +1,14 @@
-//===--- BinaryEmitter.h - collection of functions to emit code and data --===//
+//===- bolt/Core/BinaryEmitter.h - Emit code and data -----------*- 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 declarations of functions for emitting code and data into
+// a binary file.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_CORE_BINARY_EMITTER_H
@@ -20,7 +23,7 @@ namespace bolt {
 class BinaryContext;
 class BinaryFunction;
 
-/// Emit all code and data in the BinaryContext \p BC.
+/// Emit all code and data from the BinaryContext \p BC into the \p Streamer.
 ///
 /// \p OrgSecPrefix is used to modify name of emitted original sections
 /// contained in \p BC. This is done to distinguish them from sections emitted

bolt/include/bolt/Core/BinaryFunction.h

@@ -1,13 +1,24 @@
-//===--- BinaryFunction.h - Interface for machine-level function ----------===//
+//===- bolt/Core/BinaryFunction.h - Low-level function ----------*- 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
 //
 //===----------------------------------------------------------------------===//
 //
-// Interface to function in binary (machine) form. This is assembly-level
-// code representation with the control flow.
+// This file contains the declaration of the BinaryFunction class. It represents
+// a function at the lowest IR level. Typically, a BinaryFunction represents a
+// function object in a compiled and linked binary file. However, a
+// BinaryFunction can also be constructed manually, e.g. for injecting into a
+// binary file.
+//
+// A BinaryFunction could be in one of the several states described in
+// BinaryFunction::State. While in the disassembled state, it will contain a
+// list of instructions with their offsets. In the CFG state, it will contain a
+// list of BinaryBasicBlocks that form a control-flow graph. This state is best
+// suited for binary analysis and optimizations. However, sometimes it's
+// impossible to build the precise CFG due to the ambiguity of indirect
+// branches.
 //
 //===----------------------------------------------------------------------===//
 

bolt/include/bolt/Core/BinaryLoop.h

@@ -1,4 +1,4 @@
-//===--- BinaryLoop.h - Interface for machine-level loop ------------------===//
+//===- bolt/Core/BinaryLoop.h - Loop info at low-level IR -------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.

bolt/include/bolt/Core/BinarySection.h

@@ -1,11 +1,15 @@
-//===--- BinarySection.h - Interface for object file section --------------===//
+//===- bolt/Core/BinarySection.h - Section in a binary file -----*- 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 the declaration of the BinarySection class, which
+// represents a section in an executable file and contains its properties,
+// flags, contents, and relocations.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_CORE_BINARY_SECTION_H

bolt/include/bolt/Core/DebugData.h

@@ -1,12 +1,13 @@
-//===-- DebugData.h - Representation and writing of debugging information. -==//
+//===- bolt/Core/DebugData.h - Debugging information handling ---*- 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
 //
 //===----------------------------------------------------------------------===//
 //
-// Classes that represent and serialize DWARF-related entities.
+// This file contains declaration of classes that represent and serialize
+// DWARF-related entities.
 //
 //===----------------------------------------------------------------------===//
 

bolt/include/bolt/Core/DynoStats.h

@@ -1,11 +1,14 @@
-//===--- DynoStats.h ------------------------------------------------------===//
+//===- bolt/Core/DynoStats.h - Dynamic execution stats ----------*- 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
 //
 //===----------------------------------------------------------------------===//
 //
+// Keep track of statistics about the trace of execution captured in BOLT
+// profile.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_CORE_DYNO_STATS_H

bolt/include/bolt/Core/Exceptions.h

@@ -1,11 +1,13 @@
-//===-- Exceptions.h - Helpers for processing C++ exceptions --------------===//
+//===- bolt/Core/Exceptions.h - Helpers for C++ exceptions ------*- 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 declarations of classes for handling C++ exception info.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_CORE_EXCEPTIONS_H
@@ -19,7 +21,9 @@
 #include <vector>
 
 namespace llvm {
+
 class DWARFDebugFrame;
+
 namespace dwarf {
 class FDE;
 } // namespace dwarf

bolt/include/bolt/Core/JumpTable.h

@@ -1,11 +1,14 @@
-//===--- JumpTable.h - Representation of a jump table ---------------------===//
+//===- bolt/Core/JumpTable.h - Jump table at low-level IR -------*- 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 defines the JumpTable class, which represents a jump table in a
+// binary file.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_CORE_JUMP_TABLE_H

bolt/include/bolt/Core/MCPlus.h

@@ -1,11 +1,14 @@
-//===--- MCPlus.h - helpers for MCPlus-level instructions -----------------===//
+//===- bolt/Core/MCPlus.h - Helpers for MCPlus instructions -----*- 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 declarations for helper functions for adding annotations
+// to MCInst objects.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_CORE_MCPLUS_H

bolt/include/bolt/Core/MCPlusBuilder.h

@@ -1,12 +1,13 @@
-//===--- MCPlusBuilder.h - main interface for MCPlus-level instructions ---===//
+//===- bolt/Core/MCPlusBuilder.h - Interface for MCPlus ---------*- 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
 //
 //===----------------------------------------------------------------------===//
 //
-// Create/analyze/modify instructions at MC+ level.
+// This file contains the declaration of MCPlusBuilder class, which provides
+// means to create/analyze/modify instructions at MCPlus level.
 //
 //===----------------------------------------------------------------------===//
 

bolt/include/bolt/Core/ParallelUtilities.h

@@ -1,15 +1,16 @@
-//===-- ParallelUtilities.h - -----------------------------------*- C++ -*-===//
+//===- bolt/Core/ParallelUtilities.h - Parallel 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
 //
 //===----------------------------------------------------------------------===//
-// This class creates an interface that can be used to run parallel tasks that
-// operate on functions. Several scheduling criteria are supported using
-// SchedulingPolicy, and are defined by how the runtime cost should be
-// estimated.
-// If the NoThreads flags is passed, work will execute sequentially.
+//
+// This file contains functions for assisting parallel processing of binary
+// functions. Several scheduling criteria are supported using SchedulingPolicy,
+// and are defined by how the runtime cost should be estimated. If the NoThreads
+// flags is passed, all jobs will execute sequentially.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_CORE_PARALLEL_UTILITIES_H
@@ -49,7 +50,7 @@ enum SchedulingPolicy {
   SP_BB_QUADRATIC,   /// cost is estimated by the square of the BB count
 };
 
-/// Return the managed threadpool and initialize it if not intiliazed
+/// Return the managed thread pool and initialize it if not initiliazed.
 ThreadPool &getThreadPool();
 
 /// Perform the work on each BinaryFunction except those that are accepted

bolt/include/bolt/Core/Relocation.h

@@ -1,11 +1,14 @@
-//===--- Relocation.h  - Interface for object file relocations ------------===//
+//===- bolt/Core/Relocation.h - Object file relocations ---------*- 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 the declaration of Relocation class, which represents a
+// relocation in an object or a binary file.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_CORE_RELOCATION_H

bolt/include/bolt/Passes/ADRRelaxationPass.h

@@ -1,4 +1,4 @@
-//===--------- Passes/ADRRelaxationPass.h ---------------------------------===//
+//===- bolt/Passes/ADRRelaxationPass.h --------------------------*- C++ -*-===//
 //
 //                     The LLVM Compiler Infrastructure
 //
@@ -7,20 +7,20 @@
 //
 //===----------------------------------------------------------------------===//
 //
+// This file declares the ADRRelaxationPass class, which replaces AArch64
+// non-local ADR instructions with ADRP + ADD due to small offset range of ADR
+// instruction (+- 1MB) which could be easily overflowed after BOLT
+// optimizations. Such problems are usually connected with errata 843419
+// https://developer.arm.com/documentation/epm048406/2100/
+// The linker could replace ADRP instruction with ADR in some cases.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_PASSES_ADRRELAXATIONPASS_H
 #define BOLT_PASSES_ADRRELAXATIONPASS_H
 
 #include "bolt/Passes/BinaryPasses.h"
 
-// This pass replaces AArch64 non-local ADR instructions
-// with ADRP + ADD due to small offset range of ADR instruction
-// (+- 1MB) which could be easely overflowed after BOLT optimizations
-// Such problems are usually connected with errata 843419
-// https://developer.arm.com/documentation/epm048406/2100/
-// The linker could replace ADRP instruction with ADR in some cases.
-
 namespace llvm {
 namespace bolt {
 

bolt/include/bolt/Passes/Aligner.h

@@ -1,11 +1,15 @@
-//===--------- Passes/Aligner.h -------------------------------------------===//
+//===- bolt/Passes/Aligner.h - Pass for optimal code alignment --*- 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 the declaration of the Aligner class, which provides
+// alignment for code, e.g. basic block and functions, with the goal to achieve
+// the optimal performance.
+//
 //===----------------------------------------------------------------------===//
 
 #ifndef BOLT_PASSES_ALIGNER_H

bolt/include/bolt/Passes/AllocCombiner.h

@@ -1,12 +1,10 @@
-//===--- Passes/AllocCombiner.h -------------------------------------------===//
+//===- bolt/Passes/AllocCombiner.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
 //
 //===----------------------------------------------------------------------===//
-//
-//===----------------------------------------------------------------------===//
 
 #ifndef BOLT_PASSES_FRAMEDEFRAG_H
 #define BOLT_PASSES_FRAMEDEFRAG_H

bolt/include/bolt/Passes/AsmDump.h

@@ -1,4 +1,4 @@
-//===--- AsmDump.h - Dumping of a BinaryFunction into assembly ----------===//
+//===- bolt/Passes/AsmDump.h - Dump BinaryFunction as assembly --*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.

bolt/include/bolt/Passes/BinaryFunctionCallGraph.h

@@ -1,12 +1,10 @@
-//===--- Passes/CallGraph.h -----------------------------------------------===//
+//===- bolt/Passes/CallGraph.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
 //
 //===----------------------------------------------------------------------===//
-//
-//===----------------------------------------------------------------------===//
 
 #ifndef BOLT_PASSES_BINARY_FUNCTION_CALLGRAPH_H
 #define BOLT_PASSES_BINARY_FUNCTION_CALLGRAPH_H

bolt/include/bolt/Passes/BinaryPasses.h

@@ -1,4 +1,4 @@
-//===--- BinaryPasses.h - Binary-level analysis/optimization passes -------===//
+//===- bolt/Passes/BinaryPasses.h - Binary-level passes ---------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.

bolt/include/bolt/Passes/CacheMetrics.h

@@ -1,12 +1,12 @@
-//===- CacheMetrics.h - Interface for instruction cache evaluation       --===//
+//===- bolt/Passes/CacheMetrics.h - Instruction cache metrics ---*- 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
 //
 //===----------------------------------------------------------------------===//
 //
-// Functions to show metrics of cache lines
+// Functions to show metrics of cache lines.
 //
 //===----------------------------------------------------------------------===//
 

bolt/include/bolt/Passes/CallGraph.h

@@ -1,12 +1,10 @@
-//===--- Passes/CallGraph.h -----------------------------------------------===//
+//===- bolt/Passes/CallGraph.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
 //
 //===----------------------------------------------------------------------===//
-//
-//===----------------------------------------------------------------------===//
 
 #ifndef BOLT_PASSES_CALLGRAPH_H
 #define BOLT_PASSES_CALLGRAPH_H