[Lldb-commits] [lldb] [lldb] [NFC] [by AI] Add class documentation for the `PlugIn` base classes (PR #188619)

Roy Shi via lldb-commits lldb-commits at lists.llvm.org
Wed Mar 25 14:49:54 PDT 2026


https://github.com/royitaqi created https://github.com/llvm/llvm-project/pull/188619

**Generated by AI**: I asked AI to understand the plug-in system and add documentation to the base classes. The hope is that this can solidify the intended design into the code base, so that future human or ai agent can use it as ground truth (that won't be easily drifted by AI feedback loop).

**Request: code owners to verify accuracy**: Because the goal is to provide ground truth, I think it's super important to make sure that these documentation are accurate. Because I lack the expertise, I need code owners' help.
* I have read some of the added documentation and they seem to make sense to me. But I wouldn't know if they are lying or not, because I haven't touched those plugins that deeply.

**How to review/comment**: If modification to the documentation is requested, it is preferred that the reviewer can provide **the exact new text to be put into the documentation**. This can help avoid back-and-forth between me and the reviewer about what they meant and what wording should be used, etc.

>From e6607ed868d82fe1d15074fab404127c21064361 Mon Sep 17 00:00:00 2001
From: royshi <royshi at devvm24317.cln0.facebook.com>
Date: Wed, 25 Mar 2026 13:12:50 -0700
Subject: [PATCH 1/4] First attempt

---
 lldb/include/lldb/Core/Architecture.h         |  45 +++++++
 lldb/include/lldb/Core/Disassembler.h         | 104 ++++++++++++++++
 lldb/include/lldb/Core/EmulateInstruction.h   |  32 +++++
 lldb/include/lldb/Core/Highlighter.h          |  65 ++++++++++
 lldb/include/lldb/Core/ProtocolServer.h       |  38 ++++++
 .../lldb/Expression/ExpressionParser.h        |  44 +++++++
 lldb/include/lldb/Expression/REPL.h           |  49 ++++++++
 .../lldb/Interpreter/ScriptInterpreter.h      |  61 ++++++++++
 lldb/include/lldb/Symbol/SymbolFile.h         | 112 ++++++++++++++++--
 lldb/include/lldb/Symbol/SymbolLocator.h      |  25 ++++
 lldb/include/lldb/Symbol/SymbolVendor.h       |  27 +++++
 lldb/include/lldb/Symbol/TypeSystem.h         |  37 ++++++
 lldb/include/lldb/Target/ABI.h                |  86 ++++++++++++++
 .../lldb/Target/InstrumentationRuntime.h      |  81 +++++++++++++
 lldb/include/lldb/Target/Language.h           |  38 ++++++
 lldb/include/lldb/Target/LanguageRuntime.h    |  46 +++++++
 lldb/include/lldb/Target/MemoryHistory.h      |  39 ++++++
 .../include/lldb/Target/RegisterTypeBuilder.h |  34 ++++++
 lldb/include/lldb/Target/TraceExporter.h      |  24 +++-
 lldb/include/lldb/Target/UnwindAssembly.h     |  35 ++++++
 20 files changed, 1011 insertions(+), 11 deletions(-)

diff --git a/lldb/include/lldb/Core/Architecture.h b/lldb/include/lldb/Core/Architecture.h
index ed64a895717a1..72151e2da9c08 100644
--- a/lldb/include/lldb/Core/Architecture.h
+++ b/lldb/include/lldb/Core/Architecture.h
@@ -16,6 +16,51 @@
 
 namespace lldb_private {
 
+/// \class Architecture Architecture.h "lldb/Core/Architecture.h"
+/// An abstract base class for architecture-specific behavior overrides.
+///
+/// Architecture plugins provide hooks to customize LLDB's behavior for
+/// specific CPU architectures in ways that go beyond the ABI. While ABI
+/// plugins handle calling conventions and register layouts, Architecture
+/// plugins handle architecture-specific quirks in:
+///
+/// - Instruction semantics (e.g., ARM IT blocks, delay slots)
+/// - Address manipulation (e.g., Thumb bit, pointer authentication)
+/// - Breakpoint placement (e.g., adjusting breakpoint addresses)
+/// - Function prologue handling (e.g., multiple entry points)
+/// - Stack unwinding customization
+/// - Memory tagging extensions (e.g., ARM MTE, SPARC ADI)
+/// - Dynamic register reconfiguration (e.g., SVE vector length changes)
+///
+/// Architecture plugins are typically selected based on the target's
+/// architecture and are instantiated as needed. Unlike ABI plugins which
+/// are tied to a process, Architecture plugins can be used in various
+/// contexts throughout LLDB.
+///
+/// The plugin is selected via PluginManager callbacks, typically when
+/// creating a Target or during execution context setup. Multiple architecture
+/// plugins may be registered, and the first one that supports the given
+/// ArchSpec will be used.
+///
+/// Key methods that subclasses must implement:
+/// - OverrideStopInfo: Adjust stop reasons for instructions that won't execute
+///   (e.g., ARM IT blocks where the condition is false)
+///
+/// Key methods that subclasses may optionally override:
+/// - GetBytesToSkip: Handle architectures with multiple function entry points
+/// - AdjustBreakpointAddress: Fix breakpoint addresses for special cases
+/// - GetCallableLoadAddress: Add address bits needed for function calls
+/// - GetOpcodeLoadAddress: Strip address bits to get instruction addresses
+/// - GetBreakableLoadAddress: Find better breakpoint locations (e.g., before delay slots)
+/// - GetMemoryTagManager: Provide memory tagging support (MTE, ADI, etc.)
+/// - RegisterWriteCausesReconfigure: Identify registers that change layout
+/// - ReconfigureRegisterInfo: Update register layout after special writes
+///
+/// Implementations should be careful about:
+/// - Not duplicating functionality that belongs in ABI plugins
+/// - Ensuring thread-safety as methods may be called concurrently
+/// - Minimizing performance overhead as these methods are in hot paths
+/// - Only overriding methods when truly necessary for the architecture
 class Architecture : public PluginInterface {
 public:
   /// This is currently intended to handle cases where a
diff --git a/lldb/include/lldb/Core/Disassembler.h b/lldb/include/lldb/Core/Disassembler.h
index 4930cee61af10..bb7d43da7b3e3 100644
--- a/lldb/include/lldb/Core/Disassembler.h
+++ b/lldb/include/lldb/Core/Disassembler.h
@@ -56,6 +56,47 @@ class SymbolContextList;
 class Target;
 struct RegisterInfo;
 
+/// \class Instruction Disassembler.h "lldb/Core/Disassembler.h"
+/// Represents a single disassembled machine instruction.
+///
+/// An Instruction object encapsulates all information about a single machine
+/// instruction at a specific address, including:
+///
+/// - The instruction's address and address class (code/data/Thumb)
+/// - The raw opcode bytes
+/// - Mnemonic, operands, and assembly comment strings
+/// - Control flow properties (branch, call, barrier, etc.)
+/// - Instruction emulation capabilities for expression evaluation
+///
+/// Instruction objects are created by Disassembler plugins during the
+/// disassembly process. Each Disassembler plugin provides its own Instruction
+/// subclass that knows how to decode and represent instructions for that
+/// architecture.
+///
+/// Instructions are typically accessed through InstructionList containers,
+/// which are owned by Disassembler instances. They are created during
+/// disassembly operations and remain valid as long as the parent Disassembler
+/// exists.
+///
+/// Key methods that subclasses must implement:
+/// - Decode: Parse instruction bytes and populate internal state
+/// - CalculateMnemonicOperandsAndComment: Generate assembly string representation
+/// - DoesBranch: Determine if this is a branch instruction
+/// - IsLoad: Determine if this is a memory load instruction
+/// - IsBarrier: Determine if this is a barrier/fence instruction
+/// - IsAuthenticated: Determine if this uses pointer authentication
+///
+/// Key methods that subclasses may optionally override:
+/// - GetControlFlowKind: Classify control flow behavior (call/return/jump/etc.)
+/// - ParseOperands: Extract structured operand information
+/// - IsCall: Determine if this is a function call
+/// - HasDelaySlot: Indicate if this instruction has a delay slot
+///
+/// Implementations should be careful about:
+/// - Lazy computation: Only calculate strings when needed (CalculateMnemonicOperandsAndCommentIfNeeded)
+/// - Thread safety: Multiple threads may access instruction data
+/// - Memory efficiency: Avoid storing redundant information
+/// - Accurate control flow analysis: Critical for stepping and breakpoints
 class Instruction {
 public:
   Instruction(const Address &address,
@@ -291,6 +332,27 @@ std::function<bool(const Instruction::Operand &)>
 MatchOpType(Instruction::Operand::Type type);
 } // namespace OperandMatchers
 
+/// \class InstructionList Disassembler.h "lldb/Core/Disassembler.h"
+/// A container for a sequence of disassembled instructions.
+///
+/// InstructionList holds an ordered collection of Instruction objects,
+/// typically representing a contiguous range of disassembled code. It provides
+/// indexed access, search capabilities, and iteration over the instructions.
+///
+/// InstructionList objects are created and owned by Disassembler instances.
+/// They are populated during disassembly operations (DisassembleRange,
+/// DisassembleBytes, etc.) and can be accessed via
+/// Disassembler::GetInstructionList().
+///
+/// The list supports:
+/// - Random access by index
+/// - Searching by address
+/// - Finding branch instructions
+/// - Calculating total byte size
+/// - Dumping formatted assembly output
+///
+/// This class does not require subclassing - it is used as-is by all
+/// Disassembler implementations.
 class InstructionList {
 public:
   InstructionList();
@@ -399,6 +461,48 @@ class PseudoInstruction : public Instruction {
   const PseudoInstruction &operator=(const PseudoInstruction &) = delete;
 };
 
+/// \class Disassembler Disassembler.h "lldb/Core/Disassembler.h"
+/// An abstract base class for disassembler plugins.
+///
+/// Disassembler plugins convert machine code bytes into human-readable
+/// assembly language. They are essential for:
+///
+/// - Displaying assembly in the debugger UI
+/// - Mixed source/assembly views
+/// - Stepping through code at the instruction level
+/// - Understanding what code is executing at breakpoints
+/// - Analyzing crashes and examining arbitrary memory as code
+///
+/// LLDB uses disassemblers extensively during debugging. A Disassembler
+/// instance is created on-demand whenever assembly needs to be displayed,
+/// such as when using the 'disassemble' command, stepping by instruction,
+/// or viewing code in mixed mode.
+///
+/// Disassemblers are selected based on the target's architecture (ArchSpec)
+/// and optional flavor/CPU/features parameters using FindPlugin or
+/// FindPluginForTarget. The plugin manager iterates through all registered
+/// disassembler plugins until one returns a valid instance.
+///
+/// Each Disassembler instance owns an InstructionList containing the
+/// disassembled instructions. The typical workflow is:
+/// 1. Create a Disassembler via FindPlugin/FindPluginForTarget
+/// 2. Call ParseInstructions or AppendInstructions to disassemble code
+/// 3. Access results via GetInstructionList() or use PrintInstructions
+///
+/// Key methods that subclasses must implement:
+/// - DecodeInstructions: Decode machine code bytes into Instruction objects
+/// - FlavorValidForArchSpec: Validate flavor strings for this architecture
+///
+/// Most implementations also provide their own Instruction subclass that
+/// knows how to decode and represent instructions for that architecture.
+///
+/// Implementations should be careful about:
+/// - Handling invalid/data bytes gracefully (don't crash on bad input)
+/// - Supporting both live process memory and file-based disassembly
+/// - Respecting the flavor/CPU/features parameters when provided
+/// - Performance: Disassembly can be called frequently in hot paths
+/// - Thread safety: May be called from multiple threads
+/// - Memory efficiency: Don't store excessive data per instruction
 class Disassembler : public std::enable_shared_from_this<Disassembler>,
                      public PluginInterface {
 public:
diff --git a/lldb/include/lldb/Core/EmulateInstruction.h b/lldb/include/lldb/Core/EmulateInstruction.h
index ff1386cce570b..cc5a5b8657dc3 100644
--- a/lldb/include/lldb/Core/EmulateInstruction.h
+++ b/lldb/include/lldb/Core/EmulateInstruction.h
@@ -124,6 +124,38 @@ class SingleStepBreakpointLocationsPredictor {
 /// paths in a debugger (single step prediction, finding save restore
 /// locations of registers for unwinding stack frame variables) and emulating
 /// the instruction is just a bonus.
+///
+/// Plugin Selection and Instantiation:
+/// LLDB selects an EmulateInstruction plugin based on the target architecture
+/// using FindPlugin(). The function iterates through all registered plugins
+/// (e.g., EmulateInstructionARM, EmulateInstructionMIPS) and calls their
+/// CreateInstance callbacks with the ArchSpec and requested InstructionType.
+/// Each plugin's CreateInstance returns non-null only if it supports the
+/// architecture and instruction type. Plugins can optionally be selected by
+/// name to force a specific implementation.
+///
+/// Key Methods to Implement:
+/// - SupportsEmulatingInstructionsOfType(): Indicates which instruction types
+///   this plugin can emulate (e.g., eInstructionTypeAll,
+///   eInstructionTypePrologueEpilogue, eInstructionTypePCModifying)
+/// - SetTargetTriple(): Configures the emulator for the specific architecture
+/// - ReadInstruction(): Reads the instruction bytes from the current PC
+/// - EvaluateInstruction(): The core method that decodes and emulates the
+///   instruction, invoking callbacks to simulate register/memory changes
+/// - GetRegisterInfo(): Returns register metadata for the architecture
+/// - TestEmulation(): Validates the emulator against test data
+///
+/// Important Implementation Considerations:
+/// - Callbacks are the primary interface - implementations should use
+///   ReadRegister/WriteRegister/ReadMemory/WriteMemory methods which invoke
+///   the registered callbacks rather than directly accessing state
+/// - The Context parameter in callbacks is crucial for CFI generation - it
+///   must accurately describe what the instruction is doing semantically
+/// - Not all instructions need to be implemented - focus on prologue/epilogue
+///   for CFI, control flow for single-stepping, or all instructions for full
+///   emulation
+/// - Single-step prediction may require architecture-specific breakpoint
+///   location predictors (see GetSingleStepBreakpointLocationsPredictorCreator)
 
 class EmulateInstruction : public PluginInterface {
 public:
diff --git a/lldb/include/lldb/Core/Highlighter.h b/lldb/include/lldb/Core/Highlighter.h
index ffd2418a07f46..6d7e4273c678f 100644
--- a/lldb/include/lldb/Core/Highlighter.h
+++ b/lldb/include/lldb/Core/Highlighter.h
@@ -93,6 +93,58 @@ struct HighlightStyle {
 };
 
 /// Annotates source code with color attributes.
+///
+/// Highlighter plugins provide syntax highlighting for source code displayed
+/// in the debugger. These plugins apply ANSI color codes and formatting to
+/// source text based on the programming language, making code easier to read
+/// in the terminal or IDE.
+///
+/// LLDB uses highlighters in several contexts:
+/// - Source code listings (source list command, frame info with source)
+/// - Expression input in the REPL (interactive expression mode)
+/// - Disassembly with interleaved source code
+/// - Error messages showing problematic source lines
+///
+/// The HighlighterManager is responsible for selecting the appropriate
+/// highlighter for a given language and file. When LLDB needs to display
+/// source code, it calls HighlighterManager::getHighlighterFor() with the
+/// LanguageType and file path. The manager:
+/// 1. First attempts to determine the language from the Language plugin
+/// 2. Checks if a highlighter for this language is already cached
+/// 3. If not cached, queries all registered highlighter plugins via their
+///    CreateInstance callbacks, passing the LanguageType
+/// 4. Caches the result for future use
+/// 5. Falls back to DefaultHighlighter if no language-specific highlighter
+///    is available
+///
+/// Available highlighter implementations include:
+/// - ClangHighlighter: Uses Clang's lexer for C/C++/Objective-C
+/// - TreeSitterHighlighter: Uses tree-sitter parsers for multiple languages
+/// - DefaultHighlighter: No-op highlighter that returns unmodified text
+///
+/// Key methods that subclasses must implement:
+/// - GetName(): Returns a human-readable name for the highlighter
+/// - Highlight(): The main method that applies syntax highlighting to a line
+///   of code, considering the cursor position and previous lines for context
+///
+/// The Highlight() method receives:
+/// - options: A HighlightStyle containing color codes for different token types
+/// - line: The current line to highlight
+/// - cursor_pos: Optional cursor position for highlighting the current token
+/// - previous_lines: Context from earlier lines (useful for multi-line constructs)
+/// - s: Output stream where highlighted text should be written
+///
+/// Implementations should:
+/// - Parse the input text according to the language's syntax rules
+/// - Apply appropriate ColorStyle from the HighlightStyle for each token type
+///   (keywords, identifiers, literals, comments, operators, etc.)
+/// - Handle multi-line constructs like block comments or string literals by
+///   examining previous_lines
+/// - Optionally highlight the token under the cursor differently
+/// - Write the highlighted output to the stream, wrapping tokens with ANSI
+///   color codes
+/// - Be resilient to malformed or incomplete code (highlighting is often applied
+///   to code being actively edited or partial expressions)
 class Highlighter : public PluginInterface {
 public:
   Highlighter() = default;
@@ -128,6 +180,19 @@ class Highlighter : public PluginInterface {
 };
 
 /// Manages the available highlighters.
+///
+/// HighlighterManager acts as a factory and cache for Highlighter plugins.
+/// It maintains a map of language types to highlighter instances and lazily
+/// instantiates highlighters on first use. This singleton-like manager ensures
+/// that only one highlighter instance exists per language type, avoiding the
+/// overhead of repeatedly creating highlighters for frequently displayed
+/// languages.
+///
+/// The manager is thread-safe and uses a mutex to protect concurrent access
+/// to the highlighter cache. When multiple threads request highlighters
+/// simultaneously, only the first request for a given language will create
+/// the highlighter instance, and subsequent requests will reuse the cached
+/// instance.
 class HighlighterManager {
 public:
   /// Queries all known highlighter for one that can highlight some source code.
diff --git a/lldb/include/lldb/Core/ProtocolServer.h b/lldb/include/lldb/Core/ProtocolServer.h
index fcb91ea203e10..20e8c57502878 100644
--- a/lldb/include/lldb/Core/ProtocolServer.h
+++ b/lldb/include/lldb/Core/ProtocolServer.h
@@ -15,6 +15,44 @@
 
 namespace lldb_private {
 
+/// \class ProtocolServer ProtocolServer.h "lldb/Core/ProtocolServer.h"
+/// A plug-in interface definition class for protocol servers.
+///
+/// Protocol servers provide network-based debugging interfaces that allow
+/// external tools and IDEs to communicate with LLDB. Each plugin implements
+/// a specific protocol (e.g., GDB remote protocol, DAP, MCP) and handles
+/// connection management, packet parsing, and command dispatch.
+///
+/// Protocol servers are singleton instances managed by LLDB. They are created
+/// on-demand when first requested via GetOrCreate() and persist until
+/// explicitly terminated. Multiple clients can connect to the same protocol
+/// server instance if the underlying protocol supports it.
+///
+/// Plugin Selection and Instantiation:
+/// Protocol server plugins are selected by name when calling GetOrCreate().
+/// LLDB maintains a registry of available protocol server plugins, and
+/// GetOrCreate() looks up the appropriate CreateInstance callback for the
+/// requested protocol name. If a server instance already exists for that
+/// protocol, the existing instance is returned rather than creating a new one.
+///
+/// Key Methods to Implement:
+/// Subclasses must implement the following pure virtual methods:
+/// - Start(Connection): Initializes the server and begins listening for
+///   connections on the specified socket connection.
+/// - Stop(): Stops the server and closes all active connections.
+/// - GetSocket(): Returns the socket the server is listening on, or nullptr
+///   if not currently listening.
+///
+/// Thread Safety:
+/// Implementations should be thread-safe, as Start() and Stop() may be called
+/// from different threads. The base class GetOrCreate() method uses internal
+/// locking to ensure thread-safe singleton creation.
+///
+/// Lifecycle:
+/// Protocol servers are typically started during debugger initialization or
+/// when a user explicitly enables a protocol. They continue running until
+/// the debugger terminates or until Terminate() is called, which stops all
+/// active protocol server instances.
 class ProtocolServer : public PluginInterface {
 public:
   ProtocolServer() = default;
diff --git a/lldb/include/lldb/Expression/ExpressionParser.h b/lldb/include/lldb/Expression/ExpressionParser.h
index 2ef7e036909c7..e79e59bdaa769 100644
--- a/lldb/include/lldb/Expression/ExpressionParser.h
+++ b/lldb/include/lldb/Expression/ExpressionParser.h
@@ -23,6 +23,50 @@ class IRExecutionUnit;
 /// compiler that can parse expressions.
 ///
 /// ExpressionParser is the base class for llvm based Expression parsers.
+///
+/// ExpressionParser represents language-specific compilers that can parse and
+/// compile user-provided expressions for evaluation in the debugger. The most
+/// common implementation is ClangExpressionParser, which compiles C, C++, and
+/// Objective-C expressions.
+///
+/// These parsers are used whenever LLDB needs to evaluate user expressions,
+/// such as:
+/// - Interactive expression evaluation (expr command, p command, po command)
+/// - Conditional breakpoints with expression conditions
+/// - Watchpoint conditions
+/// - Variable formatters and summaries with custom code
+///
+/// LLDB instantiates expression parsers through language-specific
+/// UserExpression subclasses (e.g., ClangUserExpression). The UserExpression
+/// creates an ExpressionParser instance during its Parse() method, passing in
+/// the expression text and execution context. The parser is then responsible
+/// for:
+/// 1. Parsing the source code text into an abstract syntax tree (AST)
+/// 2. Performing semantic analysis and type checking
+/// 3. Generating LLVM IR (intermediate representation) from the AST
+/// 4. Optimizing the IR
+/// 5. Preparing the IR for execution (JIT compilation or interpretation)
+///
+/// Key methods that subclasses must implement:
+/// - Complete(): Provide code completion suggestions for partial expressions
+/// - DoPrepareForExecution(): Generate executable code from the parsed
+///   expression, including JIT compilation and setting up the execution
+///   environment
+///
+/// The parser works in conjunction with several other components:
+/// - Expression: The base class representing the expression being parsed
+/// - IRExecutionUnit: Manages the JIT-compiled code and execution
+/// - DiagnosticManager: Collects errors and warnings during parsing
+/// - ExpressionSourceCode: Wraps user expressions in necessary scaffolding
+///   code (e.g., wrapping a C++ expression in a function body)
+///
+/// Subclasses should be careful to:
+/// - Properly handle target-specific compilation flags and settings
+/// - Set up correct include paths for header files
+/// - Handle both interpreted and JIT-compiled execution paths
+/// - Manage memory and resources for the compiler instances
+/// - Provide accurate diagnostic information for parse errors
+/// - Support debug info generation when requested
 class ExpressionParser {
 public:
   /// Constructor
diff --git a/lldb/include/lldb/Expression/REPL.h b/lldb/include/lldb/Expression/REPL.h
index 809b4d8e9f5c4..414f73bc16922 100644
--- a/lldb/include/lldb/Expression/REPL.h
+++ b/lldb/include/lldb/Expression/REPL.h
@@ -19,6 +19,55 @@
 
 namespace lldb_private {
 
+/// Read-Eval-Print-Loop (REPL) interface for interactive language evaluation.
+///
+/// REPL plugins provide interactive, line-by-line code evaluation environments
+/// for specific programming languages within LLDB. These plugins allow users to
+/// execute code incrementally, see immediate results, and maintain state across
+/// multiple evaluations - similar to interactive language shells like Python's
+/// REPL or the Swift REPL.
+///
+/// What REPL Plugins Do:
+/// - Parse and evaluate code snippets incrementally as the user types them
+/// - Maintain persistent state (variables, functions) across evaluations
+/// - Provide language-specific auto-completion and auto-indentation
+/// - Display evaluation results with appropriate formatting
+/// - Handle language-specific syntax for multi-line input
+/// - Support meta-commands (commands starting with ':') for REPL control
+///
+/// How LLDB Uses REPLs:
+/// REPL instances are created via the static REPL::Create() factory method,
+/// which iterates through registered REPL plugins to find one supporting the
+/// requested language. Users typically enter a REPL via the "repl" command
+/// in LLDB's command interpreter. REPLs can be created with or without an
+/// existing target/process - "top-level" REPLs can create their own execution
+/// context, while target-attached REPLs evaluate code in an existing process.
+///
+/// The REPL runs as an IOHandler, integrating with LLDB's input/output
+/// infrastructure to provide an interactive prompt. Each line or block of
+/// code is accumulated, parsed, evaluated, and results are displayed back
+/// to the user.
+///
+/// Key Methods Subclasses Must Implement:
+/// - DoInitialization(): Perform any language-specific setup when the REPL starts
+/// - GetSourceFileBasename(): Return the filename to use for REPL code (for
+///   debug info and error messages)
+/// - GetAutoIndentCharacters(): Return characters that trigger auto-indentation
+/// - SourceIsComplete(): Determine if the current input forms a complete
+///   statement/expression that can be evaluated
+/// - GetDesiredIndentation(): Calculate the proper indentation level for the
+///   current line based on language syntax
+/// - GetLanguage(): Return the language this REPL supports
+/// - PrintOneVariable(): Format and display a single variable's value
+/// - CompleteCode(): Provide code completion suggestions for the current input
+///
+/// Implementation Considerations:
+/// - REPLs must handle both single-line expressions and multi-line statements
+/// - Maintain compilation state to enable features like incremental compilation
+/// - Parse input to detect complete vs. incomplete code blocks
+/// - Handle errors gracefully and allow continued interaction after failures
+/// - Integrate with the target's execution context if one exists
+/// - Support language-specific features like imports, declarations, and meta-commands
 class REPL : public IOHandlerDelegate,
              public llvm::RTTIExtends<REPL, llvm::RTTIRoot> {
 public:
diff --git a/lldb/include/lldb/Interpreter/ScriptInterpreter.h b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
index dac74cc8ab1da..87b647225fe1c 100644
--- a/lldb/include/lldb/Interpreter/ScriptInterpreter.h
+++ b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
@@ -146,6 +146,67 @@ class ScriptInterpreterIORedirect {
   bool m_disconnect;
 };
 
+/// Plugin interface for integrating scripting language interpreters into LLDB.
+///
+/// ScriptInterpreter plugins enable LLDB to be extended and automated using
+/// scripting languages such as Python and Lua. These plugins provide a bridge
+/// between LLDB's internal C++ API and external scripting languages, allowing
+/// users to write custom commands, data formatters, breakpoint callbacks, and
+/// more in their preferred scripting language.
+///
+/// What ScriptInterpreter Plugins Do:
+/// - Execute script code (single lines, multi-line blocks, or complete files)
+/// - Provide script-based implementations of LLDB extension points:
+///   * Custom commands (CommandObjectScript)
+///   * Type summaries and synthetic children (data formatters)
+///   * Breakpoint and watchpoint callbacks
+///   * Operating system plugins
+///   * Scripted processes, threads, and platforms
+///   * Frame recognizers
+///   * Thread plans
+/// - Expose LLDB's SB API to the scripting language
+/// - Support interactive interpreter loops for direct script execution
+/// - Handle type conversions between LLDB C++ types and script objects
+///
+/// How LLDB Uses ScriptInterpreters:
+/// Each Debugger instance has an associated ScriptInterpreter for the configured
+/// scripting language (typically Python, but can be Lua or others). The interpreter
+/// is created on-demand when first accessed. LLDB invokes the script interpreter
+/// whenever:
+/// - Users run the "script" command to execute code interactively
+/// - Script-based commands, formatters, or callbacks need to be executed
+/// - Scripts are loaded via "command script import" or similar commands
+/// - Breakpoints with scripted conditions or callbacks are evaluated
+///
+/// The ScriptInterpreter maintains the global script context and manages the
+/// lifetime of script objects that implement LLDB functionality. It also handles
+/// I/O redirection to ensure script output appears in the appropriate LLDB
+/// streams.
+///
+/// Key Methods Subclasses Must Implement:
+/// - ExecuteOneLine(): Execute a single line of script code
+/// - ExecuteInterpreterLoop(): Run an interactive interpreter session
+/// - ExecuteMultipleLines(): Execute a multi-line script block
+/// - LoadScriptingModule(): Load a script file or module
+/// - Generate*(): Methods to create script function wrappers for various
+///   extension points (breakpoint callbacks, type scripts, etc.)
+/// - Create*(): Factory methods for script-based objects (synthetic providers,
+///   commands, etc.)
+/// - Run*(): Methods to invoke script callbacks (formatted summaries, commands,
+///   etc.)
+///
+/// Implementation Considerations:
+/// - Thread safety: Multiple threads may access the interpreter simultaneously;
+///   use AcquireInterpreterLock() to synchronize access to the interpreter state
+/// - Memory management: Ensure proper reference counting/garbage collection
+///   between LLDB objects and script objects
+/// - Error handling: Script errors should be reported clearly without crashing
+///   the debugger
+/// - Performance: Minimize overhead when calling between C++ and script code
+/// - API exposure: Provide comprehensive access to LLDB functionality via the
+///   SB API layer
+/// - I/O redirection: Properly route script output through LLDB's stream
+///   infrastructure using ScriptInterpreterIORedirect
 class ScriptInterpreter : public PluginInterface {
 public:
   enum ScriptReturnType {
diff --git a/lldb/include/lldb/Symbol/SymbolFile.h b/lldb/include/lldb/Symbol/SymbolFile.h
index 6b53ba8b6acce..eed1c22e84c9e 100644
--- a/lldb/include/lldb/Symbol/SymbolFile.h
+++ b/lldb/include/lldb/Symbol/SymbolFile.h
@@ -42,12 +42,72 @@
 
 namespace lldb_private {
 
-/// Provides public interface for all SymbolFiles. Any protected
-/// virtual members should go into SymbolFileCommon; most SymbolFile
-/// implementations should inherit from SymbolFileCommon to override
-/// the behaviors except SymbolFileOnDemand which inherits
-/// public interfaces from SymbolFile and forward to underlying concrete
-/// SymbolFile implementation.
+/// Plugin interface for reading and parsing debug information from object files.
+///
+/// SymbolFile plugins are responsible for extracting debug information from
+/// executable files, shared libraries, and separate debug info files. They
+/// parse debug formats (such as DWARF, PDB, COFF, CTF, Breakpad) and provide
+/// LLDB with access to symbols, types, source line information, variables,
+/// and other debug metadata.
+///
+/// What SymbolFile Plugins Do:
+/// - Parse debug information formats (DWARF, PDB, COFF, CTF, etc.)
+/// - Provide access to compile units, functions, types, and variables
+/// - Resolve addresses to source file locations (line tables)
+/// - Look up symbols and types by name
+/// - Parse expression evaluation context (local variables, parameters)
+/// - Support type completion for forward-declared types
+/// - Handle separate debug info files (.dwo, .dwp, .dSYM, etc.)
+///
+/// How LLDB Uses SymbolFile Plugins:
+/// When a module (executable or shared library) is loaded, LLDB calls
+/// SymbolFile::FindPlugin() with the module's ObjectFile. This static method
+/// queries all registered SymbolFile plugins via their CreateInstance callbacks,
+/// asking each to report its "abilities" for that object file. The plugin
+/// reporting the highest abilities score is selected and instantiated.
+///
+/// Abilities are determined by examining the object file for recognizable
+/// debug info sections and symbols. For example, a DWARF plugin checks for
+/// .debug_info sections, while a PDB plugin checks for CodeView debug directories.
+///
+/// Once selected, the SymbolFile is attached to the Module and used throughout
+/// the module's lifetime to service debug info queries. The SymbolFile lazily
+/// parses debug information on-demand as LLDB needs it (when setting breakpoints,
+/// evaluating expressions, displaying stack frames, etc.).
+///
+/// Key Methods Subclasses Must Implement:
+/// - CalculateAbilities(): Examine the object file and return a bitmask of
+///   supported abilities (CompileUnits, LineTables, Functions, etc.)
+/// - InitializeObject(): Perform one-time initialization after selection
+/// - GetNumCompileUnits() / GetCompileUnitAtIndex(): Provide access to compilation
+///   units
+/// - ParseLanguage(), ParseFunctions(), ParseLineTable(), ParseTypes(): Parse
+///   specific kinds of debug information from compile units
+/// - ResolveSymbolContext(): Map addresses to source locations and symbols
+/// - FindGlobalVariables(), FindFunctions(), FindTypes(): Look up debug info by name
+/// - CompleteType(): Fully parse a forward-declared or incomplete type
+/// - GetTypeSystemForLanguage(): Get or create the TypeSystem for a language
+///
+/// Implementation Considerations:
+/// - Lazy parsing: Only parse debug info when needed to minimize memory usage
+///   and startup time
+/// - Thread safety: Multiple threads may query debug info; use GetModuleMutex()
+///   to synchronize access
+/// - Index building: Consider building indexes (name tables, type tables) for
+///   fast lookups in large debug info
+/// - Memory management: Large debug info can consume significant memory; consider
+///   strategies like on-demand loading (see SymbolFileOnDemand)
+/// - External files: Handle separate debug info files gracefully, reporting
+///   errors if files are missing or mismatched
+/// - Fission/split DWARF: Support debug info split across multiple files
+/// - Type uniquing: Coordinate with TypeSystem to ensure type uniqueness across
+///   modules
+///
+/// Note on Class Hierarchy:
+/// This class provides the public interface. Most implementations should inherit
+/// from SymbolFileCommon instead, which provides common implementation scaffolding.
+/// SymbolFileOnDemand is a special wrapper that inherits directly from SymbolFile
+/// to intercept and delay debug info loading.
 class SymbolFile : public PluginInterface {
   /// LLVM RTTI support.
   static char ID;
@@ -536,8 +596,44 @@ class SymbolFile : public PluginInterface {
   const SymbolFile &operator=(const SymbolFile &) = delete;
 };
 
-/// Containing protected virtual methods for child classes to override.
-/// Most actual SymbolFile implementations should inherit from this class.
+/// Base implementation class for SymbolFile plugins with common functionality.
+///
+/// SymbolFileCommon provides standard implementations of many SymbolFile
+/// interface methods that are common across different debug formats. Most
+/// concrete SymbolFile implementations (SymbolFileDWARF, SymbolFilePDB, etc.)
+/// should inherit from this class rather than directly from SymbolFile.
+///
+/// What SymbolFileCommon Provides:
+/// - Object file association and management
+/// - Compile unit caching and indexed access
+/// - Type list management for types created from debug info
+/// - Symbol table access with lazy creation
+/// - Standard implementations of GetAbilities(), GetTypeSystemForLanguage(),
+///   and other common operations
+/// - Debug info statistics tracking (index cache hits, parse times, etc.)
+/// - Type creation helpers (MakeType, CopyType) that automatically register
+///   types in the internal type list
+///
+/// Key Methods Subclasses Must Override:
+/// - CalculateAbilities(): Determine what debug info is available
+/// - CalculateNumCompileUnits(): Count compilation units in the debug info
+/// - ParseCompileUnitAtIndex(): Parse and return a specific compile unit
+/// - All the Parse*() methods from SymbolFile for parsing specific debug info
+///
+/// What This Class Handles For You:
+/// - Caching parsed compile units in m_compile_units
+/// - Managing the m_type_list for all types created from this symbol file
+/// - Implementing GetAbilities() with lazy calculation and caching
+/// - Providing access to the associated ObjectFile
+/// - Tracking statistics about debug info usage
+///
+/// Implementation Notes:
+/// This class maintains several important pieces of state:
+/// - m_objfile_sp: The ObjectFile containing the debug information
+/// - m_compile_units: Cached compilation units (lazily populated)
+/// - m_type_list: All types created/parsed from this symbol file
+/// - m_abilities: Cached abilities mask
+/// - Debug info statistics flags (index cache status, error flags)
 class SymbolFileCommon : public SymbolFile {
   /// LLVM RTTI support.
   static char ID;
diff --git a/lldb/include/lldb/Symbol/SymbolLocator.h b/lldb/include/lldb/Symbol/SymbolLocator.h
index 400b4adfd73c4..a774307473442 100644
--- a/lldb/include/lldb/Symbol/SymbolLocator.h
+++ b/lldb/include/lldb/Symbol/SymbolLocator.h
@@ -14,6 +14,31 @@
 
 namespace lldb_private {
 
+/// A plug-in interface definition class for symbol locators.
+///
+/// Symbol locator plugins are responsible for finding and downloading debug
+/// symbol files for binaries when they are not available locally. This is
+/// particularly useful in environments where debug symbols are stored
+/// separately from executables (e.g., symbol servers, build systems with
+/// separate debug info repositories).
+///
+/// The main use case is automated symbol file discovery during debugging
+/// sessions. When LLDB encounters a module with a specific UUID but cannot
+/// find matching debug symbols locally, it can use SymbolLocator plugins to
+/// attempt to locate and download the symbols from remote sources.
+///
+/// LLDB invokes SymbolLocator functionality through the PluginManager when
+/// symbols are needed but not found. The download process is asynchronous and
+/// happens on background threads to avoid blocking the debugging session.
+///
+/// Plugins should implement:
+/// - Standard PluginInterface methods (GetPluginName, etc.)
+/// - Logic to locate symbol files based on UUID and other module metadata
+/// - Download capabilities for fetching symbols from remote sources
+///
+/// Symbol locator plugins integrate with LLDB's symbol download settings
+/// (eSymbolDownloadOff, eSymbolDownloadBackground, eSymbolDownloadForeground)
+/// to control when and how symbols are fetched.
 class SymbolLocator : public PluginInterface {
 public:
   SymbolLocator() = default;
diff --git a/lldb/include/lldb/Symbol/SymbolVendor.h b/lldb/include/lldb/Symbol/SymbolVendor.h
index b060ac95b75a3..a0911823ba632 100644
--- a/lldb/include/lldb/Symbol/SymbolVendor.h
+++ b/lldb/include/lldb/Symbol/SymbolVendor.h
@@ -21,6 +21,33 @@
 
 namespace lldb_private {
 
+/// A plug-in interface definition class for symbol vendors.
+///
+/// Symbol vendor plugins abstract the process of searching for and providing
+/// debug information for a given module. Each module can have a SymbolVendor
+/// instance that manages access to its debug symbols.
+///
+/// The primary responsibility of a SymbolVendor is to locate debug information
+/// (which may be in the same file as the executable, in a separate .dSYM bundle,
+/// in a .dwp file, etc.) and create the appropriate SymbolFile object to parse
+/// that information. Platforms can subclass this to implement custom debug
+/// information discovery strategies.
+///
+/// LLDB creates a SymbolVendor for each Module during module loading via
+/// SymbolVendor::FindPlugin(), which iterates through registered plugins.
+/// If no plugin claims responsibility, a default implementation is used that
+/// looks for debug info in the module's object file or a separate symbol file.
+///
+/// Key methods to implement:
+/// - GetSymbolFile(): Returns the SymbolFile that provides actual debug info
+///
+/// Implementation notes:
+/// - SymbolVendor can aggregate multiple SymbolFile sources if needed
+/// - The vendor should parse debug information lazily (on-demand) for performance
+/// - Thread-safety is important as symbol queries can come from multiple threads
+/// - The default implementation handles common cases (object file with embedded
+///   debug info, or separate symbol file specified via Module::GetSymbolFileFileSpec)
+///
 // The symbol vendor class is designed to abstract the process of searching for
 // debug information for a given module. Platforms can subclass this class and
 // provide extra ways to find debug information. Examples would be a subclass
diff --git a/lldb/include/lldb/Symbol/TypeSystem.h b/lldb/include/lldb/Symbol/TypeSystem.h
index b3404de2a09c1..fbfb4492e775f 100644
--- a/lldb/include/lldb/Symbol/TypeSystem.h
+++ b/lldb/include/lldb/Symbol/TypeSystem.h
@@ -47,6 +47,43 @@ namespace npdb {
   class PdbAstBuilder;
 } // namespace npdb
 
+/// A plug-in interface definition class for type systems.
+///
+/// TypeSystem plugins provide language-specific type information and operations
+/// for LLDB. Each programming language (C, C++, Swift, Rust, etc.) has its own
+/// type system with unique rules for type layout, inheritance, templates/generics,
+/// and type semantics. TypeSystem plugins encapsulate these differences.
+///
+/// Type systems are central to many debugging operations including:
+/// - Evaluating expressions in the target language
+/// - Displaying variables with correct formatting
+/// - Understanding class hierarchies and polymorphism
+/// - Parsing DWARF/PDB debug information into language-specific types
+/// - Supporting language-specific data formatters
+///
+/// LLDB instantiates TypeSystem plugins on-demand via TypeSystem::CreateInstance()
+/// when debug information for a specific language is encountered. A TypeSystemMap
+/// maintains one TypeSystem instance per language per Module or Target. The
+/// selection is based on the language specified in debug info or inferred from
+/// source files.
+///
+/// Key methods that subclasses must implement:
+/// - Type creation and manipulation (GetBuiltinTypeForEncodingAndBitSize, etc.)
+/// - Type queries (IsIntegerType, IsPointerType, GetBitSize, etc.)
+/// - AST parsing from debug formats (GetDWARFParser, GetPDBParser)
+/// - Expression evaluation support (GetUserExpression, GetFunctionCaller)
+/// - Type hierarchy navigation (GetDirectBaseClassAtIndex, GetFieldAtIndex, etc.)
+///
+/// Implementation notes:
+/// - This interface extensively uses opaque pointers (lldb::opaque_compiler_type_t)
+///   to prevent generic LLDB code from depending on language-specific AST types
+/// - Opaque pointers from one TypeSystem instance should NEVER be passed to a
+///   different TypeSystem instance (even when both are for the same language)
+/// - Most functions should not be called directly but via CompilerType, CompilerDecl,
+///   or CompilerDeclContext wrapper classes
+/// - TypeSystems must be thread-safe as queries can come from multiple threads
+/// - Lazy type completion is critical for performance with large programs
+///
 /// Interface for representing a type system.
 ///
 /// Implemented by language plugins to define the type system for a given
diff --git a/lldb/include/lldb/Target/ABI.h b/lldb/include/lldb/Target/ABI.h
index 1a1f1724222e3..e7957995c2adb 100644
--- a/lldb/include/lldb/Target/ABI.h
+++ b/lldb/include/lldb/Target/ABI.h
@@ -25,6 +25,48 @@ class Type;
 
 namespace lldb_private {
 
+/// \class ABI ABI.h "lldb/Target/ABI.h"
+/// An abstract base class for ABI (Application Binary Interface) plugins.
+///
+/// ABI plugins encapsulate the calling conventions, register usage, data type
+/// layouts, and low-level details specific to a particular architecture and
+/// operating system combination. These plugins are essential for:
+///
+/// - Setting up function calls (PrepareTrivialCall)
+/// - Extracting function arguments and return values from registers/stack
+/// - Understanding register volatility and preserved registers across calls
+/// - Creating stack frame unwind plans for exception handling and backtraces
+/// - Fixing code/data addresses (e.g., ARM Thumb bit manipulation)
+/// - Validating code and stack addresses
+///
+/// LLDB creates an ABI instance for each process being debugged. The ABI is
+/// selected based on the process's architecture (ArchSpec) using the FindPlugin
+/// static method, which iterates through all registered ABI plugins until one
+/// returns a valid instance for the given architecture.
+///
+/// ABI plugins are typically instantiated early in the debugging session and
+/// remain active for the lifetime of the process. The selection happens via:
+/// ABI::FindPlugin(process_sp, arch) which queries all registered ABI
+/// implementations through the PluginManager.
+///
+/// Key methods that subclasses must implement:
+/// - PrepareTrivialCall: Set up registers/stack to call a function
+/// - GetArgumentValues: Extract function arguments from the current frame
+/// - GetReturnValueObjectImpl: Extract the return value after a function call
+/// - SetReturnValueObject: Modify the return value in a stack frame
+/// - CreateFunctionEntryUnwindPlan: Generate unwind rules at function entry
+/// - CreateDefaultUnwindPlan: Generate default unwind rules for assembly
+/// - RegisterIsVolatile: Determine if a register is caller-saved
+/// - CallFrameAddressIsValid: Validate stack pointer alignment/values
+/// - CodeAddressIsValid: Validate instruction pointer values
+/// - AugmentRegisterInfo: Add ABI-specific register metadata
+///
+/// Implementations should be careful about:
+/// - Thread safety: ABI methods may be called from multiple threads
+/// - Handling both user-space and kernel-space calling conventions
+/// - Properly masking address bits (e.g., ARM Thumb, AArch64 PAC/TBI)
+/// - Supporting multiple calling conventions on the same architecture
+/// - Correctly handling variadic functions and special argument types
 class ABI : public PluginInterface {
 public:
   struct CallArgument {
@@ -172,6 +214,24 @@ class ABI : public PluginInterface {
   const ABI &operator=(const ABI &) = delete;
 };
 
+/// \class RegInfoBasedABI ABI.h "lldb/Target/ABI.h"
+/// A concrete ABI base class that uses RegisterInfo arrays for register metadata.
+///
+/// RegInfoBasedABI is designed for ABI implementations that define their
+/// register information using static RegisterInfo arrays, which is the
+/// traditional approach used by most LLDB ABI plugins. This class provides
+/// the AugmentRegisterInfo implementation that looks up register details
+/// (DWARF/eh_frame register numbers, generic register kinds) from the
+/// RegisterInfo array provided by GetRegisterInfoArray.
+///
+/// Subclasses must implement:
+/// - GetRegisterInfoArray: Return a pointer to a static array of RegisterInfo
+///   structures that describe all registers for this ABI
+///
+/// This approach is suitable for architectures where the register set is
+/// well-defined and doesn't vary at runtime. For architectures with dynamic
+/// register information (e.g., varying vector lengths), consider using
+/// MCBasedABI instead.
 class RegInfoBasedABI : public ABI {
 public:
   void AugmentRegisterInfo(
@@ -185,6 +245,32 @@ class RegInfoBasedABI : public ABI {
   virtual const RegisterInfo *GetRegisterInfoArray(uint32_t &count) = 0;
 };
 
+/// \class MCBasedABI ABI.h "lldb/Target/ABI.h"
+/// A concrete ABI base class that derives register metadata from LLVM's MCRegisterInfo.
+///
+/// MCBasedABI is designed for ABI implementations that obtain register
+/// information from LLVM's Machine Code (MC) layer rather than maintaining
+/// separate static RegisterInfo arrays. This leverages LLVM's existing
+/// register definitions and mappings (DWARF/eh_frame register numbers),
+/// reducing code duplication and maintenance burden.
+///
+/// This class provides the AugmentRegisterInfo implementation that queries
+/// the MCRegisterInfo object (passed to the ABI constructor) to populate
+/// register metadata like DWARF numbers and eh_frame numbers.
+///
+/// Subclasses must implement:
+/// - GetGenericNum: Map register names to LLDB generic register numbers
+///   (e.g., LLDB_REGNUM_GENERIC_PC, LLDB_REGNUM_GENERIC_SP)
+///
+/// Subclasses may optionally override:
+/// - GetMCName: Transform LLDB register names to MCRegisterInfo naming
+///   conventions (e.g., case transformations, prefix changes)
+/// - GetEHAndDWARFNums: Provide custom DWARF/eh_frame number mappings
+///
+/// This approach is particularly useful for:
+/// - New architectures where LLVM support already exists
+/// - Reducing code duplication between LLDB and LLVM
+/// - Architectures with complex register aliasing schemes
 class MCBasedABI : public ABI {
 public:
   void AugmentRegisterInfo(
diff --git a/lldb/include/lldb/Target/InstrumentationRuntime.h b/lldb/include/lldb/Target/InstrumentationRuntime.h
index d2499528e97ab..336f3acb72e3a 100644
--- a/lldb/include/lldb/Target/InstrumentationRuntime.h
+++ b/lldb/include/lldb/Target/InstrumentationRuntime.h
@@ -24,6 +24,87 @@ typedef std::map<lldb::InstrumentationRuntimeType,
                  lldb::InstrumentationRuntimeSP>
     InstrumentationRuntimeCollection;
 
+/// \class InstrumentationRuntime InstrumentationRuntime.h
+/// "lldb/Target/InstrumentationRuntime.h"
+///
+/// InstrumentationRuntime plugins detect and interact with runtime
+/// instrumentation libraries that are injected into the debugged process.
+/// These libraries perform dynamic analysis such as detecting memory errors,
+/// race conditions, or other runtime issues.
+///
+/// This plugin type represents runtime sanitizers and checkers, including:
+/// - AddressSanitizer (ASan): Detects memory errors like buffer overflows,
+///   use-after-free, and memory leaks
+/// - ThreadSanitizer (TSan): Detects data races and threading issues
+/// - UndefinedBehaviorSanitizer (UBSan): Detects undefined behavior like
+///   integer overflow or null pointer dereference
+/// - BoundsSafety: Detects out-of-bounds accesses
+/// - MainThreadChecker: Detects violations of main thread requirements (macOS)
+///
+/// How LLDB Uses InstrumentationRuntime Plugins:
+///
+/// 1. Detection Phase (ModulesDidLoad):
+///    When new dynamic libraries are loaded into the process, LLDB calls
+///    InstrumentationRuntime::ModulesDidLoad() with the module list. This
+///    static method:
+///    - Queries the PluginManager for all registered InstrumentationRuntime
+///      plugins via their create_callback functions
+///    - Creates one instance of each plugin type for the process
+///    - Each instance checks if its corresponding runtime library is loaded
+///
+/// 2. Runtime Library Identification:
+///    Each plugin instance examines loaded modules to find its runtime library:
+///    - GetPatternForRuntimeLibrary() returns a regex matching the library name
+///      (e.g., "libclang_rt.asan.*" for ASan)
+///    - CheckIfRuntimeIsValid() performs additional validation on candidate
+///      modules (e.g., checking for required symbols)
+///    - MatchAllModules() returns true if all modules should be checked, not
+///      just those matching the regex pattern
+///
+/// 3. Activation Phase:
+///    Once the runtime library is identified and validated:
+///    - SetRuntimeModuleSP() caches the runtime module
+///    - Activate() is called to set up interaction with the runtime:
+///      * Typically sets breakpoints in the runtime library at reporting
+///        functions (e.g., __asan_report_error)
+///      * Stores the breakpoint ID in m_breakpoint_id
+///      * Marks the runtime as active via SetActive(true)
+///
+/// 4. Runtime Event Handling:
+///    When a breakpoint in the runtime library is hit:
+///    - The runtime typically stores diagnostic information (stack traces,
+///      error details) in memory structures
+///    - GetBacktracesFromExtendedStopInfo() can extract this information and
+///      create synthetic thread backtraces showing where the error occurred
+///    - This allows LLDB to display rich diagnostics like "heap-use-after-free
+///      on address 0x12345678, allocated by thread T0, freed by thread T1"
+///
+/// Key Methods to Implement:
+/// - GetPatternForRuntimeLibrary(): Returns a regex to match the runtime
+///   library filename (or return an empty pattern and use MatchAllModules)
+/// - CheckIfRuntimeIsValid(): Validates that a module is the actual runtime
+///   library (e.g., by checking for expected symbols or sections)
+/// - Activate(): Sets up breakpoints and any other runtime interaction after
+///   the library is loaded and validated
+/// - GetBacktracesFromExtendedStopInfo(): Optionally extracts extended
+///   diagnostic information from the runtime's internal data structures
+/// - MatchAllModules(): Return true to check all modules rather than just
+///   those matching the pattern (useful for executables or statically linked
+///   runtimes)
+///
+/// Important Implementation Considerations:
+/// - Plugins are instantiated once per process, not per runtime library
+/// - The IsActive() flag prevents duplicate activation
+/// - Breakpoints set in Activate() should be stored in m_breakpoint_id for
+///   later cleanup or management
+/// - Runtime libraries may be loaded late (after process launch) or early
+///   (before main), so ModulesDidLoad is called repeatedly as libraries load
+/// - Multiple instrumentation runtimes can be active simultaneously (e.g.,
+///   both ASan and UBSan)
+/// - Implementations should be careful with symbols that may not be present
+///   in all versions of the runtime library
+/// - Extended stop info is passed as StructuredData and must be parsed
+///   according to the runtime's specific format
 class InstrumentationRuntime
     : public std::enable_shared_from_this<InstrumentationRuntime>,
       public PluginInterface {
diff --git a/lldb/include/lldb/Target/Language.h b/lldb/include/lldb/Target/Language.h
index 4b8d4eaf262a0..a17585a958b66 100644
--- a/lldb/include/lldb/Target/Language.h
+++ b/lldb/include/lldb/Target/Language.h
@@ -36,6 +36,44 @@ class LanguageProperties : public Properties {
   bool GetEnableFilterForLineBreakpoints() const;
 };
 
+/// \class Language Language.h "lldb/Target/Language.h"
+/// A plug-in interface definition class for programming language support.
+///
+/// Language plugins provide language-specific functionality for debugging,
+/// including type formatting, expression parsing, name mangling/demangling,
+/// and method name parsing. Each plugin represents support for a specific
+/// programming language (e.g., C++, Objective-C, Swift, Rust).
+///
+/// LLDB queries language plugins to customize the debugging experience based
+/// on the source language of the code being debugged. Language plugins are
+/// created on-demand and cached globally - only one instance exists per
+/// language type for the entire LLDB session.
+///
+/// Plugin Selection:
+/// Language plugins are selected either by explicit language type (from debug
+/// info like DWARF DW_AT_language attributes) or by file extension. The
+/// FindPlugin() static method iterates through all registered language plugin
+/// callbacks until one matches the requested language or recognizes the file
+/// extension via IsSourceFile().
+///
+/// Key Responsibilities:
+/// - GetFormatters(): Provide language-specific data formatters for types
+/// - GetMethodNameVariants(): Generate alternative lookups for method names
+/// - SymbolNameFitsToLanguage(): Validate symbol name mangling schemes
+/// - IsSourceFile(): Identify source files by extension
+/// - GetExceptionResolverDescription(): Customize exception breakpoint text
+/// - GetUserEntryPointName(): Return language-specific entry point (e.g., "main")
+/// - GetDemangledFunctionNameWithoutArguments(): Parse demangled names
+///
+/// Subclasses must implement:
+/// - GetLanguageType(): Return the lldb::LanguageType this plugin handles
+/// - IsSourceFile(): Return true if the file path is a source file for this language
+///
+/// Important Notes:
+/// - Language plugins are singleton instances cached for the LLDB session
+/// - They must be stateless or use thread-safe state management
+/// - The same instance may be used concurrently across multiple targets/processes
+/// - Plugins are created via PluginManager::GetLanguageCreateCallbacks()
 class Language : public PluginInterface {
 public:
   class TypeScavenger {
diff --git a/lldb/include/lldb/Target/LanguageRuntime.h b/lldb/include/lldb/Target/LanguageRuntime.h
index 7e4c11df0da7f..fc9d165229495 100644
--- a/lldb/include/lldb/Target/LanguageRuntime.h
+++ b/lldb/include/lldb/Target/LanguageRuntime.h
@@ -58,6 +58,52 @@ class ExceptionSearchFilter : public SearchFilter {
   void UpdateModuleListIfNeeded();
 };
 
+/// \class LanguageRuntime LanguageRuntime.h "lldb/Target/LanguageRuntime.h"
+/// A plug-in interface definition class for language runtime support.
+///
+/// Language runtime plugins provide runtime-specific functionality for dynamic
+/// languages and languages with complex runtime systems (e.g., Objective-C,
+/// C++, Swift, Go). These plugins interact with the language's runtime libraries
+/// in the debugged process to provide dynamic type resolution, exception
+/// handling, expression evaluation support, and runtime-specific unwinding.
+///
+/// Unlike Language plugins (which are global singletons), LanguageRuntime
+/// plugins are per-process instances that can maintain process-specific state
+/// and interact with runtime data structures in the target process's memory.
+///
+/// Plugin Selection:
+/// LanguageRuntime plugins are instantiated when a process starts or attaches.
+/// The FindPlugin() static method is called with a Process and LanguageType,
+/// iterating through registered callbacks via PluginManager until one returns
+/// a valid instance. Multiple language runtimes can coexist in a single process
+/// (e.g., C++ and Objective-C in the same binary).
+///
+/// Key Responsibilities:
+/// - GetDynamicTypeAndAddress(): Resolve dynamic types for polymorphic objects
+/// - CouldHaveDynamicValue(): Fast check if a value might have dynamic type
+/// - FixUpDynamicType(): Adjust discovered dynamic types (e.g., add pointer)
+/// - GetObjectDescription(): Get runtime object description (e.g., -description)
+/// - CreateExceptionResolver(): Create breakpoint resolvers for exception throw/catch
+/// - GetStepThroughTrampolinePlan(): Handle stepping through runtime trampolines
+/// - GetVTableInfo(): Extract vtable information for C++ and similar languages
+/// - GetExceptionObjectForThread(): Retrieve exception objects from runtime
+/// - GetRuntimeUnwindPlan(): Provide custom unwinding for async/coroutine frames
+///
+/// Subclasses must implement:
+/// - GetLanguageType(): Return the language this runtime supports
+/// - GetDynamicTypeAndAddress(): Core dynamic type resolution logic
+/// - CouldHaveDynamicValue(): Quickly determine if dynamic type lookup makes sense
+/// - FixUpDynamicType(): Transform bare dynamic type to match static type form
+/// - GetObjectDescription(): Get string representation from runtime
+/// - CreateExceptionResolver(): Create exception breakpoint resolver
+/// - GetStepThroughTrampolinePlan(): Handle runtime-specific stepping
+///
+/// Important Notes:
+/// - Runtime instances are created per-process via create callbacks
+/// - They can cache process-specific runtime state (e.g., runtime class tables)
+/// - Must be prepared to handle invalid/stripped runtime state gracefully
+/// - Exception breakpoint support requires implementing CreateExceptionResolver()
+/// - Dynamic type resolution is performance-critical and called frequently
 class LanguageRuntime : public Runtime, public PluginInterface {
 public:
   static LanguageRuntime *FindPlugin(Process *process,
diff --git a/lldb/include/lldb/Target/MemoryHistory.h b/lldb/include/lldb/Target/MemoryHistory.h
index cba5889afbf17..18b8676838ec8 100644
--- a/lldb/include/lldb/Target/MemoryHistory.h
+++ b/lldb/include/lldb/Target/MemoryHistory.h
@@ -19,6 +19,45 @@ namespace lldb_private {
 
 typedef std::vector<lldb::ThreadSP> HistoryThreads;
 
+/// \class MemoryHistory MemoryHistory.h "lldb/Target/MemoryHistory.h"
+/// A plug-in interface definition class for memory history providers.
+///
+/// Memory history plugins track the allocation and access history of memory
+/// addresses, which is crucial for debugging memory-related issues like
+/// use-after-free, double-free, and buffer overflows. These plugins typically
+/// integrate with runtime instrumentation tools (e.g., AddressSanitizer,
+/// Malloc Stack Logging on Darwin) to provide historical stack traces showing
+/// where memory was allocated, freed, or accessed.
+///
+/// When debugging memory corruption issues, LLDB can query memory history
+/// plugins to get "history threads" - synthetic threads representing the
+/// stack traces from previous operations on a memory address. This helps
+/// developers understand what happened to memory before the current error.
+///
+/// Plugin Selection:
+/// Memory history plugins are process-specific and created on-demand via
+/// FindPlugin(). LLDB iterates through all registered memory history plugin
+/// create callbacks (from PluginManager::GetMemoryHistoryCreateCallbacks())
+/// until one returns a valid instance. Only one memory history plugin is
+/// typically active per process, and it's created when first needed.
+///
+/// Key Responsibilities:
+/// - GetHistoryThreads(): Return synthetic threads showing allocation/deallocation
+///   history for a given memory address
+///
+/// Subclasses must implement:
+/// - GetHistoryThreads(): Query the runtime instrumentation system to retrieve
+///   historical stack traces for the specified address, returning them as a
+///   vector of Thread objects that can be displayed in the debugger
+///
+/// Important Notes:
+/// - Plugins depend on runtime instrumentation being enabled in the target process
+/// - Must handle cases where no history is available for an address gracefully
+/// - History threads are synthetic and don't represent actual execution threads
+/// - Performance considerations: history lookup may involve reading significant
+///   amounts of data from the target process
+/// - The plugin should validate that the necessary runtime support is present
+///   before attempting to retrieve history
 class MemoryHistory : public std::enable_shared_from_this<MemoryHistory>,
                       public PluginInterface {
 public:
diff --git a/lldb/include/lldb/Target/RegisterTypeBuilder.h b/lldb/include/lldb/Target/RegisterTypeBuilder.h
index 7239e1d4bd126..0478333bda467 100644
--- a/lldb/include/lldb/Target/RegisterTypeBuilder.h
+++ b/lldb/include/lldb/Target/RegisterTypeBuilder.h
@@ -14,6 +14,40 @@
 
 namespace lldb_private {
 
+/// Plugin interface for building structured types to represent CPU registers.
+///
+/// RegisterTypeBuilder plugins create CompilerType representations for CPU
+/// registers that have associated register fields (flags). These structured
+/// types allow debuggers to display register contents in a human-readable
+/// format, showing individual bit fields and their meanings rather than just
+/// raw hexadecimal values.
+///
+/// LLDB uses these plugins when displaying registers that have associated
+/// RegisterFlags metadata. When a register with flags needs to be displayed,
+/// LLDB queries the active RegisterTypeBuilder plugin (if any) to create a
+/// structured type that represents the register's bit fields. This type is
+/// then used by the type system to format and display the register value.
+///
+/// Plugin Selection and Instantiation:
+/// RegisterTypeBuilder plugins are instantiated per-target and are selected
+/// based on the target's type system. For example, RegisterTypeBuilderClang
+/// is used for targets that use Clang as their primary type system. The plugin
+/// is created via the CreateInstance callback registered with the PluginManager.
+///
+/// Key Methods to Implement:
+/// - GetRegisterType(): The core method that creates a CompilerType representing
+///   a register's structure. Given a register name, its flags definition, and
+///   byte size, implementations must construct an appropriate structured type
+///   (typically a struct or class) with fields corresponding to each register
+///   flag/bit field.
+///
+/// Implementation Considerations:
+/// - Implementations should cache created types when possible, as the same
+///   register type may be requested multiple times
+/// - The returned CompilerType must accurately reflect the register's bit
+///   layout, including field positions, sizes, and types
+/// - Field names should match the flag names defined in RegisterFlags metadata
+/// - Consider endianness when constructing the type representation
 class RegisterTypeBuilder : public PluginInterface {
 public:
   ~RegisterTypeBuilder() override = default;
diff --git a/lldb/include/lldb/Target/TraceExporter.h b/lldb/include/lldb/Target/TraceExporter.h
index 52ebbd9ccafeb..64a6e619a2686 100644
--- a/lldb/include/lldb/Target/TraceExporter.h
+++ b/lldb/include/lldb/Target/TraceExporter.h
@@ -22,9 +22,27 @@ namespace lldb_private {
 /// provided by an \a lldb_private::TraceCursor into a different format that can
 /// be digested by other tools, e.g. Chrome Trace Event Profiler.
 ///
-/// Trace exporters are supposed to operate on an architecture-agnostic fashion,
-/// as a TraceCursor, which feeds the data, hides the actual trace technology
-/// being used.
+/// These plugins enable interoperability by exporting processor trace data
+/// collected by LLDB into formats that can be consumed by external analysis
+/// tools, visualization software, or other debugging systems.
+///
+/// LLDB instantiates TraceExporter plugins on-demand when a user requests
+/// trace export (e.g., via the "thread trace export" command). The plugin
+/// is selected by name via TraceExporter::FindPlugin(), which looks up the
+/// appropriate exporter in the PluginManager.
+///
+/// Key methods to implement:
+/// - Export functionality that reads from a TraceCursor and writes to the
+///   target format
+///
+/// Implementation notes:
+/// - Trace exporters are supposed to operate on an architecture-agnostic fashion,
+///   as a TraceCursor, which feeds the data, hides the actual trace technology
+///   being used
+/// - The exporter should handle streaming large trace datasets efficiently
+/// - Error handling is important as export operations can fail due to I/O issues
+/// - Examples include exporters to Chrome's trace event format, CTF, or custom
+///   analysis formats
 class TraceExporter : public PluginInterface {
 public:
   /// Create an instance of a trace exporter plugin given its name.
diff --git a/lldb/include/lldb/Target/UnwindAssembly.h b/lldb/include/lldb/Target/UnwindAssembly.h
index d20aa52d6f594..3857b65aec056 100644
--- a/lldb/include/lldb/Target/UnwindAssembly.h
+++ b/lldb/include/lldb/Target/UnwindAssembly.h
@@ -15,6 +15,41 @@
 
 namespace lldb_private {
 
+/// A plug-in interface definition class for assembly-based stack unwinding.
+///
+/// UnwindAssembly plugins provide architecture-specific instruction analysis
+/// to generate stack unwinding information by examining function assembly code.
+/// This is essential when debug information (like DWARF .eh_frame or .debug_frame)
+/// is missing, incomplete, or doesn't cover all code paths.
+///
+/// These plugins perform several critical functions:
+/// - Analyzing function prologues/epilogues to determine how the stack frame
+///   is set up and torn down
+/// - Creating UnwindPlans that describe how to restore registers at each
+///   instruction in a function
+/// - Identifying the first non-prologue instruction for breakpoint placement
+/// - Augmenting existing unwind plans with additional information from assembly
+///
+/// LLDB instantiates UnwindAssembly plugins via UnwindAssembly::FindPlugin()
+/// when unwinding is needed. The selection is based on the target architecture
+/// (ArchSpec). Each architecture typically has one UnwindAssembly implementation
+/// that understands its specific calling conventions and instruction encodings.
+///
+/// Key methods to implement:
+/// - GetNonCallSiteUnwindPlanFromAssembly(): Create a complete unwind plan by
+///   analyzing function assembly (used when no debug info is available)
+/// - AugmentUnwindPlanFromCallSite(): Enhance an existing unwind plan with
+///   information gleaned from assembly analysis
+/// - GetFastUnwindPlan(): Create a simplified unwind plan for performance-critical
+///   unwinding (e.g., during sampling)
+/// - FirstNonPrologueInsn(): Find where the function prologue ends
+///
+/// Implementation notes:
+/// - Plugins must understand architecture-specific instruction encodings
+/// - Must handle various calling conventions (e.g., ARM's multiple frame pointer modes)
+/// - Should be conservative when uncertain (invalid unwind is worse than no unwind)
+/// - Performance matters as this code runs during every stack walk
+/// - Used heavily for release builds without debug info and for system libraries
 class UnwindAssembly : public std::enable_shared_from_this<UnwindAssembly>,
                        public PluginInterface {
 public:

>From de49ef56f83a57855e3bb4608c4fcb6a4e1c0541 Mon Sep 17 00:00:00 2001
From: royshi <royshi at devvm24317.cln0.facebook.com>
Date: Wed, 25 Mar 2026 13:48:35 -0700
Subject: [PATCH 2/4] Remove "key methods" sections

---
 lldb/include/lldb/Core/Architecture.h         | 14 -----------
 lldb/include/lldb/Core/Disassembler.h         | 18 -------------
 lldb/include/lldb/Core/EmulateInstruction.h   | 11 --------
 lldb/include/lldb/Core/Highlighter.h          |  5 ----
 lldb/include/lldb/Core/ProtocolServer.h       |  8 ------
 .../lldb/Expression/ExpressionParser.h        |  6 -----
 lldb/include/lldb/Expression/REPL.h           | 13 ----------
 .../lldb/Interpreter/ScriptInterpreter.h      | 12 ---------
 lldb/include/lldb/Symbol/SymbolFile.h         | 19 --------------
 lldb/include/lldb/Symbol/SymbolVendor.h       |  3 ---
 lldb/include/lldb/Symbol/TypeSystem.h         |  7 ------
 lldb/include/lldb/Target/ABI.h                | 25 -------------------
 .../lldb/Target/InstrumentationRuntime.h      | 13 ----------
 lldb/include/lldb/Target/Language.h           |  4 ---
 lldb/include/lldb/Target/LanguageRuntime.h    |  9 -------
 lldb/include/lldb/Target/MemoryHistory.h      |  5 ----
 .../include/lldb/Target/RegisterTypeBuilder.h |  7 ------
 lldb/include/lldb/Target/TraceExporter.h      |  4 ---
 lldb/include/lldb/Target/UnwindAssembly.h     |  9 -------
 19 files changed, 192 deletions(-)

diff --git a/lldb/include/lldb/Core/Architecture.h b/lldb/include/lldb/Core/Architecture.h
index 72151e2da9c08..05e43c18c150f 100644
--- a/lldb/include/lldb/Core/Architecture.h
+++ b/lldb/include/lldb/Core/Architecture.h
@@ -42,20 +42,6 @@ namespace lldb_private {
 /// plugins may be registered, and the first one that supports the given
 /// ArchSpec will be used.
 ///
-/// Key methods that subclasses must implement:
-/// - OverrideStopInfo: Adjust stop reasons for instructions that won't execute
-///   (e.g., ARM IT blocks where the condition is false)
-///
-/// Key methods that subclasses may optionally override:
-/// - GetBytesToSkip: Handle architectures with multiple function entry points
-/// - AdjustBreakpointAddress: Fix breakpoint addresses for special cases
-/// - GetCallableLoadAddress: Add address bits needed for function calls
-/// - GetOpcodeLoadAddress: Strip address bits to get instruction addresses
-/// - GetBreakableLoadAddress: Find better breakpoint locations (e.g., before delay slots)
-/// - GetMemoryTagManager: Provide memory tagging support (MTE, ADI, etc.)
-/// - RegisterWriteCausesReconfigure: Identify registers that change layout
-/// - ReconfigureRegisterInfo: Update register layout after special writes
-///
 /// Implementations should be careful about:
 /// - Not duplicating functionality that belongs in ABI plugins
 /// - Ensuring thread-safety as methods may be called concurrently
diff --git a/lldb/include/lldb/Core/Disassembler.h b/lldb/include/lldb/Core/Disassembler.h
index bb7d43da7b3e3..9958c18e20ad9 100644
--- a/lldb/include/lldb/Core/Disassembler.h
+++ b/lldb/include/lldb/Core/Disassembler.h
@@ -78,20 +78,6 @@ struct RegisterInfo;
 /// disassembly operations and remain valid as long as the parent Disassembler
 /// exists.
 ///
-/// Key methods that subclasses must implement:
-/// - Decode: Parse instruction bytes and populate internal state
-/// - CalculateMnemonicOperandsAndComment: Generate assembly string representation
-/// - DoesBranch: Determine if this is a branch instruction
-/// - IsLoad: Determine if this is a memory load instruction
-/// - IsBarrier: Determine if this is a barrier/fence instruction
-/// - IsAuthenticated: Determine if this uses pointer authentication
-///
-/// Key methods that subclasses may optionally override:
-/// - GetControlFlowKind: Classify control flow behavior (call/return/jump/etc.)
-/// - ParseOperands: Extract structured operand information
-/// - IsCall: Determine if this is a function call
-/// - HasDelaySlot: Indicate if this instruction has a delay slot
-///
 /// Implementations should be careful about:
 /// - Lazy computation: Only calculate strings when needed (CalculateMnemonicOperandsAndCommentIfNeeded)
 /// - Thread safety: Multiple threads may access instruction data
@@ -489,10 +475,6 @@ class PseudoInstruction : public Instruction {
 /// 2. Call ParseInstructions or AppendInstructions to disassemble code
 /// 3. Access results via GetInstructionList() or use PrintInstructions
 ///
-/// Key methods that subclasses must implement:
-/// - DecodeInstructions: Decode machine code bytes into Instruction objects
-/// - FlavorValidForArchSpec: Validate flavor strings for this architecture
-///
 /// Most implementations also provide their own Instruction subclass that
 /// knows how to decode and represent instructions for that architecture.
 ///
diff --git a/lldb/include/lldb/Core/EmulateInstruction.h b/lldb/include/lldb/Core/EmulateInstruction.h
index cc5a5b8657dc3..dc5e1e3956759 100644
--- a/lldb/include/lldb/Core/EmulateInstruction.h
+++ b/lldb/include/lldb/Core/EmulateInstruction.h
@@ -134,17 +134,6 @@ class SingleStepBreakpointLocationsPredictor {
 /// architecture and instruction type. Plugins can optionally be selected by
 /// name to force a specific implementation.
 ///
-/// Key Methods to Implement:
-/// - SupportsEmulatingInstructionsOfType(): Indicates which instruction types
-///   this plugin can emulate (e.g., eInstructionTypeAll,
-///   eInstructionTypePrologueEpilogue, eInstructionTypePCModifying)
-/// - SetTargetTriple(): Configures the emulator for the specific architecture
-/// - ReadInstruction(): Reads the instruction bytes from the current PC
-/// - EvaluateInstruction(): The core method that decodes and emulates the
-///   instruction, invoking callbacks to simulate register/memory changes
-/// - GetRegisterInfo(): Returns register metadata for the architecture
-/// - TestEmulation(): Validates the emulator against test data
-///
 /// Important Implementation Considerations:
 /// - Callbacks are the primary interface - implementations should use
 ///   ReadRegister/WriteRegister/ReadMemory/WriteMemory methods which invoke
diff --git a/lldb/include/lldb/Core/Highlighter.h b/lldb/include/lldb/Core/Highlighter.h
index 6d7e4273c678f..ad61d1ff41659 100644
--- a/lldb/include/lldb/Core/Highlighter.h
+++ b/lldb/include/lldb/Core/Highlighter.h
@@ -122,11 +122,6 @@ struct HighlightStyle {
 /// - TreeSitterHighlighter: Uses tree-sitter parsers for multiple languages
 /// - DefaultHighlighter: No-op highlighter that returns unmodified text
 ///
-/// Key methods that subclasses must implement:
-/// - GetName(): Returns a human-readable name for the highlighter
-/// - Highlight(): The main method that applies syntax highlighting to a line
-///   of code, considering the cursor position and previous lines for context
-///
 /// The Highlight() method receives:
 /// - options: A HighlightStyle containing color codes for different token types
 /// - line: The current line to highlight
diff --git a/lldb/include/lldb/Core/ProtocolServer.h b/lldb/include/lldb/Core/ProtocolServer.h
index 20e8c57502878..4a115903c7632 100644
--- a/lldb/include/lldb/Core/ProtocolServer.h
+++ b/lldb/include/lldb/Core/ProtocolServer.h
@@ -35,14 +35,6 @@ namespace lldb_private {
 /// requested protocol name. If a server instance already exists for that
 /// protocol, the existing instance is returned rather than creating a new one.
 ///
-/// Key Methods to Implement:
-/// Subclasses must implement the following pure virtual methods:
-/// - Start(Connection): Initializes the server and begins listening for
-///   connections on the specified socket connection.
-/// - Stop(): Stops the server and closes all active connections.
-/// - GetSocket(): Returns the socket the server is listening on, or nullptr
-///   if not currently listening.
-///
 /// Thread Safety:
 /// Implementations should be thread-safe, as Start() and Stop() may be called
 /// from different threads. The base class GetOrCreate() method uses internal
diff --git a/lldb/include/lldb/Expression/ExpressionParser.h b/lldb/include/lldb/Expression/ExpressionParser.h
index e79e59bdaa769..74f688525f25f 100644
--- a/lldb/include/lldb/Expression/ExpressionParser.h
+++ b/lldb/include/lldb/Expression/ExpressionParser.h
@@ -47,12 +47,6 @@ class IRExecutionUnit;
 /// 4. Optimizing the IR
 /// 5. Preparing the IR for execution (JIT compilation or interpretation)
 ///
-/// Key methods that subclasses must implement:
-/// - Complete(): Provide code completion suggestions for partial expressions
-/// - DoPrepareForExecution(): Generate executable code from the parsed
-///   expression, including JIT compilation and setting up the execution
-///   environment
-///
 /// The parser works in conjunction with several other components:
 /// - Expression: The base class representing the expression being parsed
 /// - IRExecutionUnit: Manages the JIT-compiled code and execution
diff --git a/lldb/include/lldb/Expression/REPL.h b/lldb/include/lldb/Expression/REPL.h
index 414f73bc16922..1c1ea145190c6 100644
--- a/lldb/include/lldb/Expression/REPL.h
+++ b/lldb/include/lldb/Expression/REPL.h
@@ -48,19 +48,6 @@ namespace lldb_private {
 /// code is accumulated, parsed, evaluated, and results are displayed back
 /// to the user.
 ///
-/// Key Methods Subclasses Must Implement:
-/// - DoInitialization(): Perform any language-specific setup when the REPL starts
-/// - GetSourceFileBasename(): Return the filename to use for REPL code (for
-///   debug info and error messages)
-/// - GetAutoIndentCharacters(): Return characters that trigger auto-indentation
-/// - SourceIsComplete(): Determine if the current input forms a complete
-///   statement/expression that can be evaluated
-/// - GetDesiredIndentation(): Calculate the proper indentation level for the
-///   current line based on language syntax
-/// - GetLanguage(): Return the language this REPL supports
-/// - PrintOneVariable(): Format and display a single variable's value
-/// - CompleteCode(): Provide code completion suggestions for the current input
-///
 /// Implementation Considerations:
 /// - REPLs must handle both single-line expressions and multi-line statements
 /// - Maintain compilation state to enable features like incremental compilation
diff --git a/lldb/include/lldb/Interpreter/ScriptInterpreter.h b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
index 87b647225fe1c..4b5cb6b3ca53d 100644
--- a/lldb/include/lldb/Interpreter/ScriptInterpreter.h
+++ b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
@@ -183,18 +183,6 @@ class ScriptInterpreterIORedirect {
 /// I/O redirection to ensure script output appears in the appropriate LLDB
 /// streams.
 ///
-/// Key Methods Subclasses Must Implement:
-/// - ExecuteOneLine(): Execute a single line of script code
-/// - ExecuteInterpreterLoop(): Run an interactive interpreter session
-/// - ExecuteMultipleLines(): Execute a multi-line script block
-/// - LoadScriptingModule(): Load a script file or module
-/// - Generate*(): Methods to create script function wrappers for various
-///   extension points (breakpoint callbacks, type scripts, etc.)
-/// - Create*(): Factory methods for script-based objects (synthetic providers,
-///   commands, etc.)
-/// - Run*(): Methods to invoke script callbacks (formatted summaries, commands,
-///   etc.)
-///
 /// Implementation Considerations:
 /// - Thread safety: Multiple threads may access the interpreter simultaneously;
 ///   use AcquireInterpreterLock() to synchronize access to the interpreter state
diff --git a/lldb/include/lldb/Symbol/SymbolFile.h b/lldb/include/lldb/Symbol/SymbolFile.h
index eed1c22e84c9e..4cb0a7c9b402b 100644
--- a/lldb/include/lldb/Symbol/SymbolFile.h
+++ b/lldb/include/lldb/Symbol/SymbolFile.h
@@ -75,19 +75,6 @@ namespace lldb_private {
 /// parses debug information on-demand as LLDB needs it (when setting breakpoints,
 /// evaluating expressions, displaying stack frames, etc.).
 ///
-/// Key Methods Subclasses Must Implement:
-/// - CalculateAbilities(): Examine the object file and return a bitmask of
-///   supported abilities (CompileUnits, LineTables, Functions, etc.)
-/// - InitializeObject(): Perform one-time initialization after selection
-/// - GetNumCompileUnits() / GetCompileUnitAtIndex(): Provide access to compilation
-///   units
-/// - ParseLanguage(), ParseFunctions(), ParseLineTable(), ParseTypes(): Parse
-///   specific kinds of debug information from compile units
-/// - ResolveSymbolContext(): Map addresses to source locations and symbols
-/// - FindGlobalVariables(), FindFunctions(), FindTypes(): Look up debug info by name
-/// - CompleteType(): Fully parse a forward-declared or incomplete type
-/// - GetTypeSystemForLanguage(): Get or create the TypeSystem for a language
-///
 /// Implementation Considerations:
 /// - Lazy parsing: Only parse debug info when needed to minimize memory usage
 ///   and startup time
@@ -614,12 +601,6 @@ class SymbolFile : public PluginInterface {
 /// - Type creation helpers (MakeType, CopyType) that automatically register
 ///   types in the internal type list
 ///
-/// Key Methods Subclasses Must Override:
-/// - CalculateAbilities(): Determine what debug info is available
-/// - CalculateNumCompileUnits(): Count compilation units in the debug info
-/// - ParseCompileUnitAtIndex(): Parse and return a specific compile unit
-/// - All the Parse*() methods from SymbolFile for parsing specific debug info
-///
 /// What This Class Handles For You:
 /// - Caching parsed compile units in m_compile_units
 /// - Managing the m_type_list for all types created from this symbol file
diff --git a/lldb/include/lldb/Symbol/SymbolVendor.h b/lldb/include/lldb/Symbol/SymbolVendor.h
index a0911823ba632..d58aa25646526 100644
--- a/lldb/include/lldb/Symbol/SymbolVendor.h
+++ b/lldb/include/lldb/Symbol/SymbolVendor.h
@@ -38,9 +38,6 @@ namespace lldb_private {
 /// If no plugin claims responsibility, a default implementation is used that
 /// looks for debug info in the module's object file or a separate symbol file.
 ///
-/// Key methods to implement:
-/// - GetSymbolFile(): Returns the SymbolFile that provides actual debug info
-///
 /// Implementation notes:
 /// - SymbolVendor can aggregate multiple SymbolFile sources if needed
 /// - The vendor should parse debug information lazily (on-demand) for performance
diff --git a/lldb/include/lldb/Symbol/TypeSystem.h b/lldb/include/lldb/Symbol/TypeSystem.h
index fbfb4492e775f..ef6af7f658844 100644
--- a/lldb/include/lldb/Symbol/TypeSystem.h
+++ b/lldb/include/lldb/Symbol/TypeSystem.h
@@ -67,13 +67,6 @@ namespace npdb {
 /// selection is based on the language specified in debug info or inferred from
 /// source files.
 ///
-/// Key methods that subclasses must implement:
-/// - Type creation and manipulation (GetBuiltinTypeForEncodingAndBitSize, etc.)
-/// - Type queries (IsIntegerType, IsPointerType, GetBitSize, etc.)
-/// - AST parsing from debug formats (GetDWARFParser, GetPDBParser)
-/// - Expression evaluation support (GetUserExpression, GetFunctionCaller)
-/// - Type hierarchy navigation (GetDirectBaseClassAtIndex, GetFieldAtIndex, etc.)
-///
 /// Implementation notes:
 /// - This interface extensively uses opaque pointers (lldb::opaque_compiler_type_t)
 ///   to prevent generic LLDB code from depending on language-specific AST types
diff --git a/lldb/include/lldb/Target/ABI.h b/lldb/include/lldb/Target/ABI.h
index e7957995c2adb..41015e220a5d2 100644
--- a/lldb/include/lldb/Target/ABI.h
+++ b/lldb/include/lldb/Target/ABI.h
@@ -49,18 +49,6 @@ namespace lldb_private {
 /// ABI::FindPlugin(process_sp, arch) which queries all registered ABI
 /// implementations through the PluginManager.
 ///
-/// Key methods that subclasses must implement:
-/// - PrepareTrivialCall: Set up registers/stack to call a function
-/// - GetArgumentValues: Extract function arguments from the current frame
-/// - GetReturnValueObjectImpl: Extract the return value after a function call
-/// - SetReturnValueObject: Modify the return value in a stack frame
-/// - CreateFunctionEntryUnwindPlan: Generate unwind rules at function entry
-/// - CreateDefaultUnwindPlan: Generate default unwind rules for assembly
-/// - RegisterIsVolatile: Determine if a register is caller-saved
-/// - CallFrameAddressIsValid: Validate stack pointer alignment/values
-/// - CodeAddressIsValid: Validate instruction pointer values
-/// - AugmentRegisterInfo: Add ABI-specific register metadata
-///
 /// Implementations should be careful about:
 /// - Thread safety: ABI methods may be called from multiple threads
 /// - Handling both user-space and kernel-space calling conventions
@@ -224,10 +212,6 @@ class ABI : public PluginInterface {
 /// (DWARF/eh_frame register numbers, generic register kinds) from the
 /// RegisterInfo array provided by GetRegisterInfoArray.
 ///
-/// Subclasses must implement:
-/// - GetRegisterInfoArray: Return a pointer to a static array of RegisterInfo
-///   structures that describe all registers for this ABI
-///
 /// This approach is suitable for architectures where the register set is
 /// well-defined and doesn't vary at runtime. For architectures with dynamic
 /// register information (e.g., varying vector lengths), consider using
@@ -258,15 +242,6 @@ class RegInfoBasedABI : public ABI {
 /// the MCRegisterInfo object (passed to the ABI constructor) to populate
 /// register metadata like DWARF numbers and eh_frame numbers.
 ///
-/// Subclasses must implement:
-/// - GetGenericNum: Map register names to LLDB generic register numbers
-///   (e.g., LLDB_REGNUM_GENERIC_PC, LLDB_REGNUM_GENERIC_SP)
-///
-/// Subclasses may optionally override:
-/// - GetMCName: Transform LLDB register names to MCRegisterInfo naming
-///   conventions (e.g., case transformations, prefix changes)
-/// - GetEHAndDWARFNums: Provide custom DWARF/eh_frame number mappings
-///
 /// This approach is particularly useful for:
 /// - New architectures where LLVM support already exists
 /// - Reducing code duplication between LLDB and LLVM
diff --git a/lldb/include/lldb/Target/InstrumentationRuntime.h b/lldb/include/lldb/Target/InstrumentationRuntime.h
index 336f3acb72e3a..d2b4a5645951e 100644
--- a/lldb/include/lldb/Target/InstrumentationRuntime.h
+++ b/lldb/include/lldb/Target/InstrumentationRuntime.h
@@ -79,19 +79,6 @@ typedef std::map<lldb::InstrumentationRuntimeType,
 ///    - This allows LLDB to display rich diagnostics like "heap-use-after-free
 ///      on address 0x12345678, allocated by thread T0, freed by thread T1"
 ///
-/// Key Methods to Implement:
-/// - GetPatternForRuntimeLibrary(): Returns a regex to match the runtime
-///   library filename (or return an empty pattern and use MatchAllModules)
-/// - CheckIfRuntimeIsValid(): Validates that a module is the actual runtime
-///   library (e.g., by checking for expected symbols or sections)
-/// - Activate(): Sets up breakpoints and any other runtime interaction after
-///   the library is loaded and validated
-/// - GetBacktracesFromExtendedStopInfo(): Optionally extracts extended
-///   diagnostic information from the runtime's internal data structures
-/// - MatchAllModules(): Return true to check all modules rather than just
-///   those matching the pattern (useful for executables or statically linked
-///   runtimes)
-///
 /// Important Implementation Considerations:
 /// - Plugins are instantiated once per process, not per runtime library
 /// - The IsActive() flag prevents duplicate activation
diff --git a/lldb/include/lldb/Target/Language.h b/lldb/include/lldb/Target/Language.h
index a17585a958b66..aa43a3bc4ad3b 100644
--- a/lldb/include/lldb/Target/Language.h
+++ b/lldb/include/lldb/Target/Language.h
@@ -65,10 +65,6 @@ class LanguageProperties : public Properties {
 /// - GetUserEntryPointName(): Return language-specific entry point (e.g., "main")
 /// - GetDemangledFunctionNameWithoutArguments(): Parse demangled names
 ///
-/// Subclasses must implement:
-/// - GetLanguageType(): Return the lldb::LanguageType this plugin handles
-/// - IsSourceFile(): Return true if the file path is a source file for this language
-///
 /// Important Notes:
 /// - Language plugins are singleton instances cached for the LLDB session
 /// - They must be stateless or use thread-safe state management
diff --git a/lldb/include/lldb/Target/LanguageRuntime.h b/lldb/include/lldb/Target/LanguageRuntime.h
index fc9d165229495..87b3258a0fa18 100644
--- a/lldb/include/lldb/Target/LanguageRuntime.h
+++ b/lldb/include/lldb/Target/LanguageRuntime.h
@@ -89,15 +89,6 @@ class ExceptionSearchFilter : public SearchFilter {
 /// - GetExceptionObjectForThread(): Retrieve exception objects from runtime
 /// - GetRuntimeUnwindPlan(): Provide custom unwinding for async/coroutine frames
 ///
-/// Subclasses must implement:
-/// - GetLanguageType(): Return the language this runtime supports
-/// - GetDynamicTypeAndAddress(): Core dynamic type resolution logic
-/// - CouldHaveDynamicValue(): Quickly determine if dynamic type lookup makes sense
-/// - FixUpDynamicType(): Transform bare dynamic type to match static type form
-/// - GetObjectDescription(): Get string representation from runtime
-/// - CreateExceptionResolver(): Create exception breakpoint resolver
-/// - GetStepThroughTrampolinePlan(): Handle runtime-specific stepping
-///
 /// Important Notes:
 /// - Runtime instances are created per-process via create callbacks
 /// - They can cache process-specific runtime state (e.g., runtime class tables)
diff --git a/lldb/include/lldb/Target/MemoryHistory.h b/lldb/include/lldb/Target/MemoryHistory.h
index 18b8676838ec8..cc87f8922d891 100644
--- a/lldb/include/lldb/Target/MemoryHistory.h
+++ b/lldb/include/lldb/Target/MemoryHistory.h
@@ -45,11 +45,6 @@ typedef std::vector<lldb::ThreadSP> HistoryThreads;
 /// - GetHistoryThreads(): Return synthetic threads showing allocation/deallocation
 ///   history for a given memory address
 ///
-/// Subclasses must implement:
-/// - GetHistoryThreads(): Query the runtime instrumentation system to retrieve
-///   historical stack traces for the specified address, returning them as a
-///   vector of Thread objects that can be displayed in the debugger
-///
 /// Important Notes:
 /// - Plugins depend on runtime instrumentation being enabled in the target process
 /// - Must handle cases where no history is available for an address gracefully
diff --git a/lldb/include/lldb/Target/RegisterTypeBuilder.h b/lldb/include/lldb/Target/RegisterTypeBuilder.h
index 0478333bda467..5575c56e4af8a 100644
--- a/lldb/include/lldb/Target/RegisterTypeBuilder.h
+++ b/lldb/include/lldb/Target/RegisterTypeBuilder.h
@@ -34,13 +34,6 @@ namespace lldb_private {
 /// is used for targets that use Clang as their primary type system. The plugin
 /// is created via the CreateInstance callback registered with the PluginManager.
 ///
-/// Key Methods to Implement:
-/// - GetRegisterType(): The core method that creates a CompilerType representing
-///   a register's structure. Given a register name, its flags definition, and
-///   byte size, implementations must construct an appropriate structured type
-///   (typically a struct or class) with fields corresponding to each register
-///   flag/bit field.
-///
 /// Implementation Considerations:
 /// - Implementations should cache created types when possible, as the same
 ///   register type may be requested multiple times
diff --git a/lldb/include/lldb/Target/TraceExporter.h b/lldb/include/lldb/Target/TraceExporter.h
index 64a6e619a2686..dfdf2c11e3e50 100644
--- a/lldb/include/lldb/Target/TraceExporter.h
+++ b/lldb/include/lldb/Target/TraceExporter.h
@@ -31,10 +31,6 @@ namespace lldb_private {
 /// is selected by name via TraceExporter::FindPlugin(), which looks up the
 /// appropriate exporter in the PluginManager.
 ///
-/// Key methods to implement:
-/// - Export functionality that reads from a TraceCursor and writes to the
-///   target format
-///
 /// Implementation notes:
 /// - Trace exporters are supposed to operate on an architecture-agnostic fashion,
 ///   as a TraceCursor, which feeds the data, hides the actual trace technology
diff --git a/lldb/include/lldb/Target/UnwindAssembly.h b/lldb/include/lldb/Target/UnwindAssembly.h
index 3857b65aec056..71d2a94d6e29b 100644
--- a/lldb/include/lldb/Target/UnwindAssembly.h
+++ b/lldb/include/lldb/Target/UnwindAssembly.h
@@ -35,15 +35,6 @@ namespace lldb_private {
 /// (ArchSpec). Each architecture typically has one UnwindAssembly implementation
 /// that understands its specific calling conventions and instruction encodings.
 ///
-/// Key methods to implement:
-/// - GetNonCallSiteUnwindPlanFromAssembly(): Create a complete unwind plan by
-///   analyzing function assembly (used when no debug info is available)
-/// - AugmentUnwindPlanFromCallSite(): Enhance an existing unwind plan with
-///   information gleaned from assembly analysis
-/// - GetFastUnwindPlan(): Create a simplified unwind plan for performance-critical
-///   unwinding (e.g., during sampling)
-/// - FirstNonPrologueInsn(): Find where the function prologue ends
-///
 /// Implementation notes:
 /// - Plugins must understand architecture-specific instruction encodings
 /// - Must handle various calling conventions (e.g., ARM's multiple frame pointer modes)

>From 40366a9f11099157e2c863567f8acf3244a750dc Mon Sep 17 00:00:00 2001
From: royshi <royshi at devvm24317.cln0.facebook.com>
Date: Wed, 25 Mar 2026 14:22:44 -0700
Subject: [PATCH 3/4] Fix format

---
 lldb/include/lldb/Core/Disassembler.h         |  3 ++-
 lldb/include/lldb/Core/Highlighter.h          |  6 +++--
 lldb/include/lldb/Expression/REPL.h           |  3 ++-
 .../lldb/Interpreter/ScriptInterpreter.h      | 17 ++++++------
 lldb/include/lldb/Symbol/SymbolFile.h         | 27 ++++++++++---------
 lldb/include/lldb/Symbol/SymbolVendor.h       | 17 +++++++-----
 lldb/include/lldb/Symbol/TypeSystem.h         | 21 ++++++++-------
 lldb/include/lldb/Target/ABI.h                |  6 +++--
 lldb/include/lldb/Target/Language.h           |  6 +++--
 lldb/include/lldb/Target/LanguageRuntime.h    | 22 +++++++++------
 lldb/include/lldb/Target/MemoryHistory.h      |  6 +++--
 .../include/lldb/Target/RegisterTypeBuilder.h |  3 ++-
 lldb/include/lldb/Target/TraceExporter.h      |  6 +++--
 lldb/include/lldb/Target/UnwindAssembly.h     | 18 ++++++++-----
 14 files changed, 97 insertions(+), 64 deletions(-)

diff --git a/lldb/include/lldb/Core/Disassembler.h b/lldb/include/lldb/Core/Disassembler.h
index 9958c18e20ad9..a766f5c827bfd 100644
--- a/lldb/include/lldb/Core/Disassembler.h
+++ b/lldb/include/lldb/Core/Disassembler.h
@@ -79,7 +79,8 @@ struct RegisterInfo;
 /// exists.
 ///
 /// Implementations should be careful about:
-/// - Lazy computation: Only calculate strings when needed (CalculateMnemonicOperandsAndCommentIfNeeded)
+/// - Lazy computation: Only calculate strings when needed
+/// (CalculateMnemonicOperandsAndCommentIfNeeded)
 /// - Thread safety: Multiple threads may access instruction data
 /// - Memory efficiency: Avoid storing redundant information
 /// - Accurate control flow analysis: Critical for stepping and breakpoints
diff --git a/lldb/include/lldb/Core/Highlighter.h b/lldb/include/lldb/Core/Highlighter.h
index ad61d1ff41659..47ff5d1982942 100644
--- a/lldb/include/lldb/Core/Highlighter.h
+++ b/lldb/include/lldb/Core/Highlighter.h
@@ -126,7 +126,8 @@ struct HighlightStyle {
 /// - options: A HighlightStyle containing color codes for different token types
 /// - line: The current line to highlight
 /// - cursor_pos: Optional cursor position for highlighting the current token
-/// - previous_lines: Context from earlier lines (useful for multi-line constructs)
+/// - previous_lines: Context from earlier lines (useful for multi-line
+/// constructs)
 /// - s: Output stream where highlighted text should be written
 ///
 /// Implementations should:
@@ -138,7 +139,8 @@ struct HighlightStyle {
 /// - Optionally highlight the token under the cursor differently
 /// - Write the highlighted output to the stream, wrapping tokens with ANSI
 ///   color codes
-/// - Be resilient to malformed or incomplete code (highlighting is often applied
+/// - Be resilient to malformed or incomplete code (highlighting is often
+/// applied
 ///   to code being actively edited or partial expressions)
 class Highlighter : public PluginInterface {
 public:
diff --git a/lldb/include/lldb/Expression/REPL.h b/lldb/include/lldb/Expression/REPL.h
index 1c1ea145190c6..1cf2cd8aa9f21 100644
--- a/lldb/include/lldb/Expression/REPL.h
+++ b/lldb/include/lldb/Expression/REPL.h
@@ -54,7 +54,8 @@ namespace lldb_private {
 /// - Parse input to detect complete vs. incomplete code blocks
 /// - Handle errors gracefully and allow continued interaction after failures
 /// - Integrate with the target's execution context if one exists
-/// - Support language-specific features like imports, declarations, and meta-commands
+/// - Support language-specific features like imports, declarations, and
+/// meta-commands
 class REPL : public IOHandlerDelegate,
              public llvm::RTTIExtends<REPL, llvm::RTTIRoot> {
 public:
diff --git a/lldb/include/lldb/Interpreter/ScriptInterpreter.h b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
index 4b5cb6b3ca53d..a223baedeb6c8 100644
--- a/lldb/include/lldb/Interpreter/ScriptInterpreter.h
+++ b/lldb/include/lldb/Interpreter/ScriptInterpreter.h
@@ -169,23 +169,24 @@ class ScriptInterpreterIORedirect {
 /// - Handle type conversions between LLDB C++ types and script objects
 ///
 /// How LLDB Uses ScriptInterpreters:
-/// Each Debugger instance has an associated ScriptInterpreter for the configured
-/// scripting language (typically Python, but can be Lua or others). The interpreter
-/// is created on-demand when first accessed. LLDB invokes the script interpreter
-/// whenever:
+/// Each Debugger instance has an associated ScriptInterpreter for the
+/// configured scripting language (typically Python, but can be Lua or others).
+/// The interpreter is created on-demand when first accessed. LLDB invokes the
+/// script interpreter whenever:
 /// - Users run the "script" command to execute code interactively
 /// - Script-based commands, formatters, or callbacks need to be executed
 /// - Scripts are loaded via "command script import" or similar commands
 /// - Breakpoints with scripted conditions or callbacks are evaluated
 ///
 /// The ScriptInterpreter maintains the global script context and manages the
-/// lifetime of script objects that implement LLDB functionality. It also handles
-/// I/O redirection to ensure script output appears in the appropriate LLDB
-/// streams.
+/// lifetime of script objects that implement LLDB functionality. It also
+/// handles I/O redirection to ensure script output appears in the appropriate
+/// LLDB streams.
 ///
 /// Implementation Considerations:
 /// - Thread safety: Multiple threads may access the interpreter simultaneously;
-///   use AcquireInterpreterLock() to synchronize access to the interpreter state
+///   use AcquireInterpreterLock() to synchronize access to the interpreter
+///   state
 /// - Memory management: Ensure proper reference counting/garbage collection
 ///   between LLDB objects and script objects
 /// - Error handling: Script errors should be reported clearly without crashing
diff --git a/lldb/include/lldb/Symbol/SymbolFile.h b/lldb/include/lldb/Symbol/SymbolFile.h
index 4cb0a7c9b402b..fb8ebb89a9a15 100644
--- a/lldb/include/lldb/Symbol/SymbolFile.h
+++ b/lldb/include/lldb/Symbol/SymbolFile.h
@@ -42,7 +42,8 @@
 
 namespace lldb_private {
 
-/// Plugin interface for reading and parsing debug information from object files.
+/// Plugin interface for reading and parsing debug information from object
+/// files.
 ///
 /// SymbolFile plugins are responsible for extracting debug information from
 /// executable files, shared libraries, and separate debug info files. They
@@ -62,18 +63,19 @@ namespace lldb_private {
 /// How LLDB Uses SymbolFile Plugins:
 /// When a module (executable or shared library) is loaded, LLDB calls
 /// SymbolFile::FindPlugin() with the module's ObjectFile. This static method
-/// queries all registered SymbolFile plugins via their CreateInstance callbacks,
-/// asking each to report its "abilities" for that object file. The plugin
-/// reporting the highest abilities score is selected and instantiated.
+/// queries all registered SymbolFile plugins via their CreateInstance
+/// callbacks, asking each to report its "abilities" for that object file. The
+/// plugin reporting the highest abilities score is selected and instantiated.
 ///
 /// Abilities are determined by examining the object file for recognizable
 /// debug info sections and symbols. For example, a DWARF plugin checks for
-/// .debug_info sections, while a PDB plugin checks for CodeView debug directories.
+/// .debug_info sections, while a PDB plugin checks for CodeView debug
+/// directories.
 ///
 /// Once selected, the SymbolFile is attached to the Module and used throughout
 /// the module's lifetime to service debug info queries. The SymbolFile lazily
-/// parses debug information on-demand as LLDB needs it (when setting breakpoints,
-/// evaluating expressions, displaying stack frames, etc.).
+/// parses debug information on-demand as LLDB needs it (when setting
+/// breakpoints, evaluating expressions, displaying stack frames, etc.).
 ///
 /// Implementation Considerations:
 /// - Lazy parsing: Only parse debug info when needed to minimize memory usage
@@ -82,7 +84,8 @@ namespace lldb_private {
 ///   to synchronize access
 /// - Index building: Consider building indexes (name tables, type tables) for
 ///   fast lookups in large debug info
-/// - Memory management: Large debug info can consume significant memory; consider
+/// - Memory management: Large debug info can consume significant memory;
+/// consider
 ///   strategies like on-demand loading (see SymbolFileOnDemand)
 /// - External files: Handle separate debug info files gracefully, reporting
 ///   errors if files are missing or mismatched
@@ -91,10 +94,10 @@ namespace lldb_private {
 ///   modules
 ///
 /// Note on Class Hierarchy:
-/// This class provides the public interface. Most implementations should inherit
-/// from SymbolFileCommon instead, which provides common implementation scaffolding.
-/// SymbolFileOnDemand is a special wrapper that inherits directly from SymbolFile
-/// to intercept and delay debug info loading.
+/// This class provides the public interface. Most implementations should
+/// inherit from SymbolFileCommon instead, which provides common implementation
+/// scaffolding. SymbolFileOnDemand is a special wrapper that inherits directly
+/// from SymbolFile to intercept and delay debug info loading.
 class SymbolFile : public PluginInterface {
   /// LLVM RTTI support.
   static char ID;
diff --git a/lldb/include/lldb/Symbol/SymbolVendor.h b/lldb/include/lldb/Symbol/SymbolVendor.h
index d58aa25646526..f288b2350376a 100644
--- a/lldb/include/lldb/Symbol/SymbolVendor.h
+++ b/lldb/include/lldb/Symbol/SymbolVendor.h
@@ -28,10 +28,10 @@ namespace lldb_private {
 /// instance that manages access to its debug symbols.
 ///
 /// The primary responsibility of a SymbolVendor is to locate debug information
-/// (which may be in the same file as the executable, in a separate .dSYM bundle,
-/// in a .dwp file, etc.) and create the appropriate SymbolFile object to parse
-/// that information. Platforms can subclass this to implement custom debug
-/// information discovery strategies.
+/// (which may be in the same file as the executable, in a separate .dSYM
+/// bundle, in a .dwp file, etc.) and create the appropriate SymbolFile object
+/// to parse that information. Platforms can subclass this to implement custom
+/// debug information discovery strategies.
 ///
 /// LLDB creates a SymbolVendor for each Module during module loading via
 /// SymbolVendor::FindPlugin(), which iterates through registered plugins.
@@ -40,10 +40,13 @@ namespace lldb_private {
 ///
 /// Implementation notes:
 /// - SymbolVendor can aggregate multiple SymbolFile sources if needed
-/// - The vendor should parse debug information lazily (on-demand) for performance
-/// - Thread-safety is important as symbol queries can come from multiple threads
+/// - The vendor should parse debug information lazily (on-demand) for
+/// performance
+/// - Thread-safety is important as symbol queries can come from multiple
+/// threads
 /// - The default implementation handles common cases (object file with embedded
-///   debug info, or separate symbol file specified via Module::GetSymbolFileFileSpec)
+///   debug info, or separate symbol file specified via
+///   Module::GetSymbolFileFileSpec)
 ///
 // The symbol vendor class is designed to abstract the process of searching for
 // debug information for a given module. Platforms can subclass this class and
diff --git a/lldb/include/lldb/Symbol/TypeSystem.h b/lldb/include/lldb/Symbol/TypeSystem.h
index ef6af7f658844..2018cf38bb0ef 100644
--- a/lldb/include/lldb/Symbol/TypeSystem.h
+++ b/lldb/include/lldb/Symbol/TypeSystem.h
@@ -51,8 +51,9 @@ namespace npdb {
 ///
 /// TypeSystem plugins provide language-specific type information and operations
 /// for LLDB. Each programming language (C, C++, Swift, Rust, etc.) has its own
-/// type system with unique rules for type layout, inheritance, templates/generics,
-/// and type semantics. TypeSystem plugins encapsulate these differences.
+/// type system with unique rules for type layout, inheritance,
+/// templates/generics, and type semantics. TypeSystem plugins encapsulate these
+/// differences.
 ///
 /// Type systems are central to many debugging operations including:
 /// - Evaluating expressions in the target language
@@ -61,18 +62,20 @@ namespace npdb {
 /// - Parsing DWARF/PDB debug information into language-specific types
 /// - Supporting language-specific data formatters
 ///
-/// LLDB instantiates TypeSystem plugins on-demand via TypeSystem::CreateInstance()
-/// when debug information for a specific language is encountered. A TypeSystemMap
-/// maintains one TypeSystem instance per language per Module or Target. The
-/// selection is based on the language specified in debug info or inferred from
-/// source files.
+/// LLDB instantiates TypeSystem plugins on-demand via
+/// TypeSystem::CreateInstance() when debug information for a specific language
+/// is encountered. A TypeSystemMap maintains one TypeSystem instance per
+/// language per Module or Target. The selection is based on the language
+/// specified in debug info or inferred from source files.
 ///
 /// Implementation notes:
-/// - This interface extensively uses opaque pointers (lldb::opaque_compiler_type_t)
+/// - This interface extensively uses opaque pointers
+/// (lldb::opaque_compiler_type_t)
 ///   to prevent generic LLDB code from depending on language-specific AST types
 /// - Opaque pointers from one TypeSystem instance should NEVER be passed to a
 ///   different TypeSystem instance (even when both are for the same language)
-/// - Most functions should not be called directly but via CompilerType, CompilerDecl,
+/// - Most functions should not be called directly but via CompilerType,
+/// CompilerDecl,
 ///   or CompilerDeclContext wrapper classes
 /// - TypeSystems must be thread-safe as queries can come from multiple threads
 /// - Lazy type completion is critical for performance with large programs
diff --git a/lldb/include/lldb/Target/ABI.h b/lldb/include/lldb/Target/ABI.h
index 41015e220a5d2..d0a793aac610b 100644
--- a/lldb/include/lldb/Target/ABI.h
+++ b/lldb/include/lldb/Target/ABI.h
@@ -203,7 +203,8 @@ class ABI : public PluginInterface {
 };
 
 /// \class RegInfoBasedABI ABI.h "lldb/Target/ABI.h"
-/// A concrete ABI base class that uses RegisterInfo arrays for register metadata.
+/// A concrete ABI base class that uses RegisterInfo arrays for register
+/// metadata.
 ///
 /// RegInfoBasedABI is designed for ABI implementations that define their
 /// register information using static RegisterInfo arrays, which is the
@@ -230,7 +231,8 @@ class RegInfoBasedABI : public ABI {
 };
 
 /// \class MCBasedABI ABI.h "lldb/Target/ABI.h"
-/// A concrete ABI base class that derives register metadata from LLVM's MCRegisterInfo.
+/// A concrete ABI base class that derives register metadata from LLVM's
+/// MCRegisterInfo.
 ///
 /// MCBasedABI is designed for ABI implementations that obtain register
 /// information from LLVM's Machine Code (MC) layer rather than maintaining
diff --git a/lldb/include/lldb/Target/Language.h b/lldb/include/lldb/Target/Language.h
index aa43a3bc4ad3b..5f5c3b7db9f69 100644
--- a/lldb/include/lldb/Target/Language.h
+++ b/lldb/include/lldb/Target/Language.h
@@ -62,13 +62,15 @@ class LanguageProperties : public Properties {
 /// - SymbolNameFitsToLanguage(): Validate symbol name mangling schemes
 /// - IsSourceFile(): Identify source files by extension
 /// - GetExceptionResolverDescription(): Customize exception breakpoint text
-/// - GetUserEntryPointName(): Return language-specific entry point (e.g., "main")
+/// - GetUserEntryPointName(): Return language-specific entry point (e.g.,
+/// "main")
 /// - GetDemangledFunctionNameWithoutArguments(): Parse demangled names
 ///
 /// Important Notes:
 /// - Language plugins are singleton instances cached for the LLDB session
 /// - They must be stateless or use thread-safe state management
-/// - The same instance may be used concurrently across multiple targets/processes
+/// - The same instance may be used concurrently across multiple
+/// targets/processes
 /// - Plugins are created via PluginManager::GetLanguageCreateCallbacks()
 class Language : public PluginInterface {
 public:
diff --git a/lldb/include/lldb/Target/LanguageRuntime.h b/lldb/include/lldb/Target/LanguageRuntime.h
index 87b3258a0fa18..b4d084550fdcb 100644
--- a/lldb/include/lldb/Target/LanguageRuntime.h
+++ b/lldb/include/lldb/Target/LanguageRuntime.h
@@ -63,9 +63,10 @@ class ExceptionSearchFilter : public SearchFilter {
 ///
 /// Language runtime plugins provide runtime-specific functionality for dynamic
 /// languages and languages with complex runtime systems (e.g., Objective-C,
-/// C++, Swift, Go). These plugins interact with the language's runtime libraries
-/// in the debugged process to provide dynamic type resolution, exception
-/// handling, expression evaluation support, and runtime-specific unwinding.
+/// C++, Swift, Go). These plugins interact with the language's runtime
+/// libraries in the debugged process to provide dynamic type resolution,
+/// exception handling, expression evaluation support, and runtime-specific
+/// unwinding.
 ///
 /// Unlike Language plugins (which are global singletons), LanguageRuntime
 /// plugins are per-process instances that can maintain process-specific state
@@ -82,18 +83,23 @@ class ExceptionSearchFilter : public SearchFilter {
 /// - GetDynamicTypeAndAddress(): Resolve dynamic types for polymorphic objects
 /// - CouldHaveDynamicValue(): Fast check if a value might have dynamic type
 /// - FixUpDynamicType(): Adjust discovered dynamic types (e.g., add pointer)
-/// - GetObjectDescription(): Get runtime object description (e.g., -description)
-/// - CreateExceptionResolver(): Create breakpoint resolvers for exception throw/catch
-/// - GetStepThroughTrampolinePlan(): Handle stepping through runtime trampolines
+/// - GetObjectDescription(): Get runtime object description (e.g.,
+/// -description)
+/// - CreateExceptionResolver(): Create breakpoint resolvers for exception
+/// throw/catch
+/// - GetStepThroughTrampolinePlan(): Handle stepping through runtime
+/// trampolines
 /// - GetVTableInfo(): Extract vtable information for C++ and similar languages
 /// - GetExceptionObjectForThread(): Retrieve exception objects from runtime
-/// - GetRuntimeUnwindPlan(): Provide custom unwinding for async/coroutine frames
+/// - GetRuntimeUnwindPlan(): Provide custom unwinding for async/coroutine
+/// frames
 ///
 /// Important Notes:
 /// - Runtime instances are created per-process via create callbacks
 /// - They can cache process-specific runtime state (e.g., runtime class tables)
 /// - Must be prepared to handle invalid/stripped runtime state gracefully
-/// - Exception breakpoint support requires implementing CreateExceptionResolver()
+/// - Exception breakpoint support requires implementing
+/// CreateExceptionResolver()
 /// - Dynamic type resolution is performance-critical and called frequently
 class LanguageRuntime : public Runtime, public PluginInterface {
 public:
diff --git a/lldb/include/lldb/Target/MemoryHistory.h b/lldb/include/lldb/Target/MemoryHistory.h
index cc87f8922d891..1e7afc34c2af7 100644
--- a/lldb/include/lldb/Target/MemoryHistory.h
+++ b/lldb/include/lldb/Target/MemoryHistory.h
@@ -42,11 +42,13 @@ typedef std::vector<lldb::ThreadSP> HistoryThreads;
 /// typically active per process, and it's created when first needed.
 ///
 /// Key Responsibilities:
-/// - GetHistoryThreads(): Return synthetic threads showing allocation/deallocation
+/// - GetHistoryThreads(): Return synthetic threads showing
+/// allocation/deallocation
 ///   history for a given memory address
 ///
 /// Important Notes:
-/// - Plugins depend on runtime instrumentation being enabled in the target process
+/// - Plugins depend on runtime instrumentation being enabled in the target
+/// process
 /// - Must handle cases where no history is available for an address gracefully
 /// - History threads are synthetic and don't represent actual execution threads
 /// - Performance considerations: history lookup may involve reading significant
diff --git a/lldb/include/lldb/Target/RegisterTypeBuilder.h b/lldb/include/lldb/Target/RegisterTypeBuilder.h
index 5575c56e4af8a..124791bbbfb34 100644
--- a/lldb/include/lldb/Target/RegisterTypeBuilder.h
+++ b/lldb/include/lldb/Target/RegisterTypeBuilder.h
@@ -32,7 +32,8 @@ namespace lldb_private {
 /// RegisterTypeBuilder plugins are instantiated per-target and are selected
 /// based on the target's type system. For example, RegisterTypeBuilderClang
 /// is used for targets that use Clang as their primary type system. The plugin
-/// is created via the CreateInstance callback registered with the PluginManager.
+/// is created via the CreateInstance callback registered with the
+/// PluginManager.
 ///
 /// Implementation Considerations:
 /// - Implementations should cache created types when possible, as the same
diff --git a/lldb/include/lldb/Target/TraceExporter.h b/lldb/include/lldb/Target/TraceExporter.h
index dfdf2c11e3e50..11b8d557ae9a6 100644
--- a/lldb/include/lldb/Target/TraceExporter.h
+++ b/lldb/include/lldb/Target/TraceExporter.h
@@ -32,11 +32,13 @@ namespace lldb_private {
 /// appropriate exporter in the PluginManager.
 ///
 /// Implementation notes:
-/// - Trace exporters are supposed to operate on an architecture-agnostic fashion,
+/// - Trace exporters are supposed to operate on an architecture-agnostic
+/// fashion,
 ///   as a TraceCursor, which feeds the data, hides the actual trace technology
 ///   being used
 /// - The exporter should handle streaming large trace datasets efficiently
-/// - Error handling is important as export operations can fail due to I/O issues
+/// - Error handling is important as export operations can fail due to I/O
+/// issues
 /// - Examples include exporters to Chrome's trace event format, CTF, or custom
 ///   analysis formats
 class TraceExporter : public PluginInterface {
diff --git a/lldb/include/lldb/Target/UnwindAssembly.h b/lldb/include/lldb/Target/UnwindAssembly.h
index 71d2a94d6e29b..ea8616c7c8655 100644
--- a/lldb/include/lldb/Target/UnwindAssembly.h
+++ b/lldb/include/lldb/Target/UnwindAssembly.h
@@ -19,8 +19,8 @@ namespace lldb_private {
 ///
 /// UnwindAssembly plugins provide architecture-specific instruction analysis
 /// to generate stack unwinding information by examining function assembly code.
-/// This is essential when debug information (like DWARF .eh_frame or .debug_frame)
-/// is missing, incomplete, or doesn't cover all code paths.
+/// This is essential when debug information (like DWARF .eh_frame or
+/// .debug_frame) is missing, incomplete, or doesn't cover all code paths.
 ///
 /// These plugins perform several critical functions:
 /// - Analyzing function prologues/epilogues to determine how the stack frame
@@ -32,15 +32,19 @@ namespace lldb_private {
 ///
 /// LLDB instantiates UnwindAssembly plugins via UnwindAssembly::FindPlugin()
 /// when unwinding is needed. The selection is based on the target architecture
-/// (ArchSpec). Each architecture typically has one UnwindAssembly implementation
-/// that understands its specific calling conventions and instruction encodings.
+/// (ArchSpec). Each architecture typically has one UnwindAssembly
+/// implementation that understands its specific calling conventions and
+/// instruction encodings.
 ///
 /// Implementation notes:
 /// - Plugins must understand architecture-specific instruction encodings
-/// - Must handle various calling conventions (e.g., ARM's multiple frame pointer modes)
-/// - Should be conservative when uncertain (invalid unwind is worse than no unwind)
+/// - Must handle various calling conventions (e.g., ARM's multiple frame
+/// pointer modes)
+/// - Should be conservative when uncertain (invalid unwind is worse than no
+/// unwind)
 /// - Performance matters as this code runs during every stack walk
-/// - Used heavily for release builds without debug info and for system libraries
+/// - Used heavily for release builds without debug info and for system
+/// libraries
 class UnwindAssembly : public std::enable_shared_from_this<UnwindAssembly>,
                        public PluginInterface {
 public:

>From 96783e434e625ae7f7c68237455a25ca14bb1b53 Mon Sep 17 00:00:00 2001
From: royshi <royshi at devvm24317.cln0.facebook.com>
Date: Wed, 25 Mar 2026 14:27:12 -0700
Subject: [PATCH 4/4] Fix removals of existing comments

---
 lldb/include/lldb/Symbol/SymbolFile.h    | 10 ++++++++++
 lldb/include/lldb/Target/TraceExporter.h |  4 ++++
 2 files changed, 14 insertions(+)

diff --git a/lldb/include/lldb/Symbol/SymbolFile.h b/lldb/include/lldb/Symbol/SymbolFile.h
index fb8ebb89a9a15..804a9bded7675 100644
--- a/lldb/include/lldb/Symbol/SymbolFile.h
+++ b/lldb/include/lldb/Symbol/SymbolFile.h
@@ -45,6 +45,13 @@ namespace lldb_private {
 /// Plugin interface for reading and parsing debug information from object
 /// files.
 ///
+/// Provides public interface for all SymbolFiles. Any protected
+/// virtual members should go into SymbolFileCommon; most SymbolFile
+/// implementations should inherit from SymbolFileCommon to override
+/// the behaviors except SymbolFileOnDemand which inherits
+/// public interfaces from SymbolFile and forward to underlying concrete
+/// SymbolFile implementation.
+///
 /// SymbolFile plugins are responsible for extracting debug information from
 /// executable files, shared libraries, and separate debug info files. They
 /// parse debug formats (such as DWARF, PDB, COFF, CTF, Breakpad) and provide
@@ -588,6 +595,9 @@ class SymbolFile : public PluginInterface {
 
 /// Base implementation class for SymbolFile plugins with common functionality.
 ///
+/// Containing protected virtual methods for child classes to override.
+/// Most actual SymbolFile implementations should inherit from this class.
+///
 /// SymbolFileCommon provides standard implementations of many SymbolFile
 /// interface methods that are common across different debug formats. Most
 /// concrete SymbolFile implementations (SymbolFileDWARF, SymbolFilePDB, etc.)
diff --git a/lldb/include/lldb/Target/TraceExporter.h b/lldb/include/lldb/Target/TraceExporter.h
index 11b8d557ae9a6..9a0487f5c7715 100644
--- a/lldb/include/lldb/Target/TraceExporter.h
+++ b/lldb/include/lldb/Target/TraceExporter.h
@@ -22,6 +22,10 @@ namespace lldb_private {
 /// provided by an \a lldb_private::TraceCursor into a different format that can
 /// be digested by other tools, e.g. Chrome Trace Event Profiler.
 ///
+/// Trace exporters are supposed to operate on an architecture-agnostic fashion,
+/// as a TraceCursor, which feeds the data, hides the actual trace technology
+/// being used.
+///
 /// These plugins enable interoperability by exporting processor trace data
 /// collected by LLDB into formats that can be consumed by external analysis
 /// tools, visualization software, or other debugging systems.



More information about the lldb-commits mailing list