[lldb] Document the SBDebugger public interface

[JDevlieghere]

Despite our best efforts, improved documentation of the public API remains a common request amongst its users. We have the Docstrings files in the bindings directory, but coverage and quality varies greatly by class.

I've noticed that we a bunch of Doxygen comments throughout LLDB, but relatively few in the SB API, which might be explained by the aforementioned Docstrings files. With #147617, we can leverage the Doxygen documentation to automatically generate Pydoc documentation for the Python bindings using SWIG.

Going forward, I'd like to invest in the Doxygen documentation for the public API. This PR is a first step in that direction. The Doxygen comments will benefit both C++ and Python clients. Additionally, the compiler (through the -Wdocumentation flag) can help catch quality and correctness issues.

[llvmbot]

@llvm/pr-subscribers-lldb

Author: Jonas Devlieghere (JDevlieghere)

Changes

Despite our best efforts, improved documentation of the public API remains a common request amongst its users. We have the Docstrings files in the bindings directory, but coverage and quality varies greatly by class.

I've noticed that we a bunch of Doxygen comments throughout LLDB, but relatively few in the SB API, which might be explained by the aforementioned Docstrings files. With #147617, we can leverage the Doxygen documentation to automatically generate Pydoc documentation for the Python bindings using SWIG.

Going forward, I'd like to invest in the Doxygen documentation for the public API. This PR is a first step in that direction. The Doxygen comments will benefit both C++ and Python clients. Additionally, the compiler (through the -Wdocumentation flag) can help catch quality and correctness issues.

---

Patch is 38.72 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/147621.diff

1 Files Affected:

• (modified) lldb/include/lldb/API/SBDebugger.h (+821-47)

diff --git a/lldb/include/lldb/API/SBDebugger.h b/lldb/include/lldb/API/SBDebugger.h
index 192fbee9c0c6d..81e86d54a7998 100644
--- a/lldb/include/lldb/API/SBDebugger.h
+++ b/lldb/include/lldb/API/SBDebugger.h
@@ -44,6 +44,7 @@ class LLDB_API SBInputReader {
 
 class LLDB_API SBDebugger {
 public:
+  /// Broadcast bit definitions for the SBDebugger.
   FLAGS_ANONYMOUS_ENUM() {
     eBroadcastBitProgress = lldb::DebuggerBroadcastBit::eBroadcastBitProgress,
     eBroadcastBitWarning = lldb::DebuggerBroadcastBit::eBroadcastBitWarning,
@@ -55,16 +56,33 @@ class LLDB_API SBDebugger {
     eBroadcastBitExternalProgressCategory =
         lldb::DebuggerBroadcastBit::eBroadcastBitExternalProgressCategory,
   };
+
+  /// Default constructor creates an invalid SBDebugger instance.
   SBDebugger();
 
   SBDebugger(const lldb::SBDebugger &rhs);
 
   ~SBDebugger();
 
+  /// Get the broadcaster class name.
+  ///
+  /// \return The name of the broadcaster class.
   static const char *GetBroadcasterClass();
 
+  /// Check if a specific language is supported by LLDB.
+  ///
+  /// \param [in] language
+  ///   The language to check.
+  ///
+  /// \return
+  ///   True if the language is supported, false otherwise.
   static bool SupportsLanguage(lldb::LanguageType language);
 
+  /// Get the broadcaster associated with this debugger.
+  ///
+  /// \return
+  ///   A broadcaster object that allows subscribing to events from this
+  ///   debugger.
   lldb::SBBroadcaster GetBroadcaster();
 
   /// Get progress data from a SBEvent whose type is eBroadcastBitProgress.
@@ -106,44 +124,122 @@ class LLDB_API SBDebugger {
                                           bool &is_debugger_specific);
 #endif
 
+  /// Get structured progress data from an event.
+  ///
+  /// \param [in] event
+  ///   The event to extract the progress information from.
+  ///
+  /// \return
+  ///   A structured data object containing progress information, or an invalid
+  ///   SBStructuredData if the event was not a progress event.
   static lldb::SBStructuredData
   GetProgressDataFromEvent(const lldb::SBEvent &event);
 
+  /// Get diagnostic information from an event.
+  ///
+  /// \param [in] event
+  ///   The event to extract the diagnostic information from.
+  ///
+  /// \return
+  ///   A structured data object containing diagnostic information, or an
+  ///   invalid SBStructuredData if the event was not a diagnostic event.
   static lldb::SBStructuredData
   GetDiagnosticFromEvent(const lldb::SBEvent &event);
 
+  /// Assignment operator.
   lldb::SBDebugger &operator=(const lldb::SBDebugger &rhs);
 
+  /// Initialize LLDB and its subsystems.
+  ///
+  /// This function should be called before any other LLDB functions. It
+  /// initializes all required subsystems for proper LLDB functionality.
   static void Initialize();
 
+  /// Initialize the LLDB debugger subsystem with error handling.
+  ///
+  /// Similar to Initialize(), but returns an error if initialization fails.
+  ///
+  /// \return
+  ///   An SBError object that indicates success or failure.
   static lldb::SBError InitializeWithErrorHandling();
 
+  /// Configure LLDB to print a stack trace when it crashes.
   static void PrintStackTraceOnError();
 
+  /// Configure LLDB to print diagnostic information when it crashes.
   static void PrintDiagnosticsOnError();
 
+  /// Terminate LLDB and its subsystems.
+  ///
+  /// This should be called when LLDB is no longer needed.
   static void Terminate();
 
+  /// Create a new debugger instance (deprecated).
+  ///
+  /// \return
+  ///   A new SBDebugger object.
   LLDB_DEPRECATED_FIXME("Use one of the other Create variants", "Create(bool)")
   static lldb::SBDebugger Create();
 
+  /// Create a new debugger instance.
+  ///
+  /// \param [in] source_init_files
+  ///   If true, the debugger will source .lldbinit files from the home
+  ///   directory and current directory.
+  ///
+  /// \return
+  ///   A new SBDebugger object.
   static lldb::SBDebugger Create(bool source_init_files);
 
+  /// Create a new debugger instance with a custom log handler.
+  ///
+  /// \param [in] source_init_files
+  ///   If true, the debugger will source .lldbinit files from the home
+  ///   directory and current directory.
+  ///
+  /// \param [in] log_callback
+  ///   A callback function to handle log messages.
+  ///
+  /// \param [in] baton
+  ///   A user data pointer passed to the log callback function.
+  ///
+  /// \return
+  ///   A new SBDebugger object.
   static lldb::SBDebugger Create(bool source_init_files,
                                  lldb::LogOutputCallback log_callback,
                                  void *baton);
 
+  /// Destroy a debugger instance.
+  ///
+  /// \param [in] debugger
+  ///   The debugger instance to destroy.
   static void Destroy(lldb::SBDebugger &debugger);
 
+  /// Notify the debugger that system memory pressure has been detected.
+  ///
+  /// This can be used to free up memory resources by clearing caches.
   static void MemoryPressureDetected();
 
+  /// Check if this is a valid SBDebugger object.
+  ///
+  /// \return
+  ///   True if this object is valid, false otherwise.
   explicit operator bool() const;
 
+  /// Check if this is a valid SBDebugger object.
+  ///
+  /// \return
+  ///   True if this object is valid, false otherwise.
   bool IsValid() const;
 
+  /// Clear this debugger instance.
+  ///
+  /// This will close all IO handlers and reset the debugger to its initial
+  /// state.
   void Clear();
 
-  /// Getting a specific setting value into SBStructuredData format.
+  /// Get debugger settings as structured data.
+  ///
   /// Client can specify empty string or null to get all settings.
   ///
   /// Example usages:
@@ -153,70 +249,221 @@ class LLDB_API SBDebugger {
   /// lldb::SBStructuredData settings = debugger.GetSetting("target.arg0");
   /// lldb::SBStructuredData settings = debugger.GetSetting("target");
   ///
-  /// \param[out] setting
+  /// \param[in] setting
   ///   Property setting path to retrieve values. e.g "target.source-map"
   ///
+  /// \return
+  ///   An SBStructuredData object containing the requested settings.
   lldb::SBStructuredData GetSetting(const char *setting = nullptr);
 
+  /// Set whether the debugger should run in asynchronous mode.
+  ///
+  /// When in asynchronous mode, events are processed on a background thread.
+  ///
+  /// \param [in] b
+  ///   True to enable asynchronous mode, false for synchronous mode.
   void SetAsync(bool b);
 
+  /// Get whether the debugger is running in asynchronous mode.
+  ///
+  /// \return
+  ///   True if the debugger is in asynchronous mode, false otherwise.
   bool GetAsync();
 
+  /// Set whether to skip loading .lldbinit files.
+  ///
+  /// \param [in] b
+  ///   True to skip loading LLDB init files, false to load them.
   void SkipLLDBInitFiles(bool b);
 
+  /// Set whether to skip loading application-specific .lldbinit files.
+  ///
+  /// \param [in] b
+  ///   True to skip loading application init files, false to load them.
   void SkipAppInitFiles(bool b);
 
 #ifndef SWIG
+  /// Set the input file handle for the debugger.
+  ///
+  /// \param [in] f
+  ///   The file handle to use for input.
+  ///
+  /// \param [in] transfer_ownership
+  ///   If true, the debugger takes ownership of the file handle.
   void SetInputFileHandle(FILE *f, bool transfer_ownership);
 
+  /// Set the output file handle for the debugger.
+  ///
+  /// \param [in] f
+  ///   The file handle to use for output.
+  ///
+  /// \param [in] transfer_ownership
+  ///   If true, the debugger takes ownership of the file handle.
   void SetOutputFileHandle(FILE *f, bool transfer_ownership);
 
+  /// Set the error file handle for the debugger.
+  ///
+  /// \param [in] f
+  ///   The file handle to use for error output.
+  ///
+  /// \param [in] transfer_ownership
+  ///   If true, the debugger takes ownership of the file handle.
   void SetErrorFileHandle(FILE *f, bool transfer_ownership);
 #endif
 
 #ifndef SWIG
+  /// Get the input file handle for the debugger.
+  ///
+  /// \return
+  ///   The current input file handle.
   FILE *GetInputFileHandle();
 
+  /// Get the output file handle for the debugger.
+  ///
+  /// \return
+  ///   The current output file handle.
   FILE *GetOutputFileHandle();
 
+  /// Get the error file handle for the debugger.
+  ///
+  /// \return
+  ///   The current error file handle.
   FILE *GetErrorFileHandle();
 #endif
 
+  /// Set the input from a string.
+  ///
+  /// \param [in] data
+  ///   The string to use as input.
+  ///
+  /// \return
+  ///   An SBError object indicating success or failure.
   SBError SetInputString(const char *data);
 
+  /// Set the input file for the debugger.
+  ///
+  /// \param [in] file
+  ///   The file to use for input.
+  ///
+  /// \return
+  ///   An SBError object indicating success or failure.
   SBError SetInputFile(SBFile file);
 
+  /// Set the output file for the debugger.
+  ///
+  /// \param [in] file
+  ///   The file to use for output.
+  ///
+  /// \return
+  ///   An SBError object indicating success or failure.
   SBError SetOutputFile(SBFile file);
 
+  /// Set the error file for the debugger.
+  ///
+  /// \param [in] file
+  ///   The file to use for error output.
+  ///
+  /// \return
+  ///   An SBError object indicating success or failure.
   SBError SetErrorFile(SBFile file);
 
+  /// Set the input file for the debugger using a FileSP.
+  ///
+  /// \param [in] file
+  ///   The file to use for input.
+  ///
+  /// \return
+  ///   An SBError object indicating success or failure.
   SBError SetInputFile(FileSP file);
 
+  /// Set the output file for the debugger using a FileSP.
+  ///
+  /// \param [in] file
+  ///   The file to use for output.
+  ///
+  /// \return
+  ///   An SBError object indicating success or failure.
   SBError SetOutputFile(FileSP file);
 
+  /// Set the error file for the debugger using a FileSP.
+  ///
+  /// \param [in] file
+  ///   The file to use for error output.
+  ///
+  /// \return
+  ///   An SBError object indicating success or failure.
   SBError SetErrorFile(FileSP file);
 
+  /// Get the input file for the debugger.
+  ///
+  /// \return
+  ///   The current input file.
   SBFile GetInputFile();
 
+  /// Get the output file for the debugger.
+  ///
+  /// \return
+  ///   The current output file.
   SBFile GetOutputFile();
 
+  /// Get the error file for the debugger.
+  ///
+  /// \return
+  ///   The current error file.
   SBFile GetErrorFile();
 
+  /// Save the current terminal state.
+  ///
+  /// This should be called before modifying terminal settings.
   void SaveInputTerminalState();
 
+  /// Restore the previously saved terminal state.
   void RestoreInputTerminalState();
 
+  /// Get the command interpreter for this debugger.
+  ///
+  /// \return
+  ///   The command interpreter object.
   lldb::SBCommandInterpreter GetCommandInterpreter();
 
+  /// Execute a command in the command interpreter.
+  ///
+  /// \param [in] command
+  ///   The command to execute.
   void HandleCommand(const char *command);
 
+  /// Request an interrupt of the current operation.
   void RequestInterrupt();
+
+  /// Cancel a previously requested interrupt.
   void CancelInterruptRequest();
+
+  /// Check if an interrupt has been requested.
+  ///
+  /// \return
+  ///   True if an interrupt has been requested, false otherwise.
   bool InterruptRequested();
 
+  /// Get the listener associated with this debugger.
+  ///
+  /// \return
+  ///   The listener object.
   lldb::SBListener GetListener();
 
 #ifndef SWIG
+  /// Handle a process event (deprecated).
+  ///
+  /// \param [in] process
+  ///   The process that generated the event.
+  ///
+  /// \param [in] event
+  ///   The event to handle.
+  ///
+  /// \param [in] out
+  ///   The file to write standard output to.
+  ///
+  /// \param [in] err
+  ///   The file to write error output to.
   LLDB_DEPRECATED_FIXME(
       "Use HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, "
       "SBFile) or HandleProcessEvent(const SBProcess &, const SBEvent &, "
@@ -226,266 +473,770 @@ class LLDB_API SBDebugger {
                           const lldb::SBEvent &event, FILE *out, FILE *err);
 #endif
 
+  /// Handle a process event.
+  ///
+  /// \param [in] process
+  ///   The process that generated the event.
+  ///
+  /// \param [in] event
+  ///   The event to handle.
+  ///
+  /// \param [in] out
+  ///   The file to write standard output to.
+  ///
+  /// \param [in] err
+  ///   The file to write error output to.
   void HandleProcessEvent(const lldb::SBProcess &process,
                           const lldb::SBEvent &event, SBFile out, SBFile err);
 
 #ifdef SWIG
+  /// Handle a process event using FileSP objects.
+  ///
+  /// \param [in] process
+  ///   The process that generated the event.
+  ///
+  /// \param [in] event
+  ///   The event to handle.
+  ///
+  /// \param [in] out
+  ///   The file to write standard output to.
+  ///
+  /// \param [in] err
+  ///   The file to write error output to.
   void HandleProcessEvent(const lldb::SBProcess &process,
                           const lldb::SBEvent &event, FileSP BORROWED, FileSP BORROWED);
 #else
+  /// Handle a process event using FileSP objects.
+  ///
+  /// \param [in] process
+  ///   The process that generated the event.
+  ///
+  /// \param [in] event
+  ///   The event to handle.
+  ///
+  /// \param [in] out
+  ///   The file to write standard output to.
+  ///
+  /// \param [in] err
+  ///   The file to write error output to.
   void HandleProcessEvent(const lldb::SBProcess &process,
                           const lldb::SBEvent &event, FileSP out, FileSP err);
 #endif
 
+  /// Create a target with the specified parameters.
+  ///
+  /// \param [in] filename
+  ///   The name of the executable file to debug.
+  ///
+  /// \param [in] target_triple
+  ///   The target triple string (e.g., "x86_64-apple-macosx").
+  ///
+  /// \param [in] platform_name
+  ///   The name of the platform to use.
+  ///
+  /// \param [in] add_dependent_modules
+  ///   Whether to add dependent modules to the target.
+  ///
+  /// \param [out] error
+  ///   An SBError object that will be set if there is an error.
+  ///
+  /// \return
+  ///   An SBTarget object.
   lldb::SBTarget CreateTarget(const char *filename, const char *target_triple,
                               const char *platform_name,
                               bool add_dependent_modules, lldb::SBError &error);
 
+  /// Create a target with the specified file and target triple.
+  ///
+  /// \param [in] filename
+  ///   The name of the executable file to debug.
+  ///
+  /// \param [in] target_triple
+  ///   The target triple string (e.g., "x86_64-apple-macosx").
+  ///
+  /// \return
+  ///   An SBTarget object.
   lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename,
                                                      const char *target_triple);
 
+  /// Create a target with the specified file and architecture.
+  ///
+  /// \param [in] filename
+  ///   The name of the executable file to debug.
+  ///
+  /// \param [in] archname
+  ///   The name of the architecture (e.g., "x86_64").
+  ///
+  /// \return
+  ///   An SBTarget object.
   lldb::SBTarget CreateTargetWithFileAndArch(const char *filename,
                                              const char *archname);
 
+  /// Create a target with the specified file.
+  ///
+  /// \param [in] filename
+  ///   The name of the executable file to debug.
+  ///
+  /// \return
+  ///   An SBTarget object.
   lldb::SBTarget CreateTarget(const char *filename);
 
+  /// Get the dummy target.
+  ///
+  /// The dummy target is used when no target is available.
+  ///
+  /// \return
+  ///   The dummy target.
   lldb::SBTarget GetDummyTarget();
 
 #ifndef SWIG
-  // Dispatch telemery from client to server if client-telemetry is enabled
-  // (by vendor), otherwise the data is ignored.
-  // Invoking this from python client (with SWIG) is not supported.
+  /// Dispatch telemetry data from client to server.
+  ///
+  /// This is used to send telemetry data from the client to the server if
+  /// client-telemetry is enabled. If not enabled, the data is ignored.
+  ///
+  /// \param [in] data
+  ///   The telemetry data to dispatch.
   void DispatchClientTelemetry(const lldb::SBStructuredData &data);
 #endif
 
-  // Return true if target is deleted from the target list of the debugger.
+  /// Delete a target from the debugger.
+  ///
+  /// \param [in] target
+  ///   The target to delete.
+  ///
+  /// \return
+  ///   True if the target was successfully deleted, false otherwise.
   bool DeleteTarget(lldb::SBTarget &target);
 
+  /// Get a target by index.
+  ///
+  /// \param [in] idx
+  ///   The index of the target to retrieve.
+  ///
+  /// \return
+  ///   The target at the specified index.
   lldb::SBTarget GetTargetAtIndex(uint32_t idx);
 
+  /// Get the index of a target.
+  ///
+  /// \param [in] target
+  ///   The target to find the index of.
+  ///
+  /// \return
+  ///   The index of the target, or UINT32_MAX if not found.
   uint32_t GetIndexOfTarget(lldb::SBTarget target);
 
+  /// Find a target with the specified process ID.
+  ///
+  /// \param [in] pid
+  ///   The process ID to search for.
+  ///
+  /// \return
+  ///   The target with the specified process ID, or an invalid target if not
+  ///   found.
   lldb::SBTarget FindTargetWithProcessID(lldb::pid_t pid);
 
+  /// Find a target with the specified file and architecture.
+  ///
+  /// \param [in] filename
+  ///   The name of the executable file.
+  ///
+  /// \param [in] arch
+  ///   The name of the architecture.
+  ///
+  /// \return
+  ///   The target with the specified file and architecture, or an invalid
+  ///   target if not found.
   lldb::SBTarget FindTargetWithFileAndArch(const char *filename,
                                            const char *arch);
 
+  /// Get the number of targets in the debugger.
+  ///
+  /// \return
+  ///   The number of targets.
   uint32_t GetNumTargets();
 
+  /// Get the currently selected target.
+  ///
+  /// \return
+  ///   The selected target.
   lldb::SBTarget GetSelectedTarget();
 
+  /// Set the selected target.
+  ///
+  /// \param [in] target
+  ///   The target to select.
   void SetSelectedTarget(SBTarget &target);
 
+  /// Get the selected platform.
+  ///
+  /// \return
+  ///   The selected platform.
   lldb::SBPlatform GetSelectedPlatform();
 
+  /// Set the selected platform.
+  ///
+  /// \param [in] platform
+  ///   The platform to select.
   void SetSelectedPlatform(lldb::SBPlatform &platform);
 
   /// Get the number of currently active platforms.
+  ///
+  /// \return
+  ///   The number of active platforms.
   uint32_t GetNumPlatforms();
 
   /// Get one of the currently active platforms.
+  ///
+  /// \param [in] idx
+  ///   The index of the platform to retrieve.
+  ///
+  /// \return
+  ///   The platform at the specified index.
   lldb::SBPlatform GetPlatformAtIndex(uint32_t idx);
 
   /// Get the number of available platforms.
   ///
   /// The return value should match the number of entries output by the
   /// "platform list" command.
+  ///
+  /// \return
+  ///   The number of available platforms.
   uint32_t GetNumAvailablePlatforms();
 
-  /// Get the name and description of one of the available platforms.
+  /// Get information about one of the available platforms.
   ///
   /// \param[in] idx
-  ///     Zero-based index of the platform for which info should be retrieved,
-  ///     must be less than the value returned by GetNumAvailablePlatforms().
+  ///   Zero-based index of the platform for which info should be retrieved,
+  ///   must be less than the value returned by GetNumAvailablePlatforms().
+  ///
+  /// \return
+  ///   A structured data object containing platform information.
   lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx);
 
+  /// Get the source manager for this debugger.
+  ///
+  /// \return
+  ///   The source manager object.
   lldb::SBSourceManager GetSourceManager();
 
-  // REMOVE: just for a quick fix, need to expose platforms through
-  // SBPlatform from this class.
+  /// Set the current platform by name.
+  ///
+  /// \param [in] platform_name
+  ///   The name of the platform to set as current.
+  ///
+  /// \return
+  ///   An SBError object ...
[truncated]

[labath]

We definitely need more documentation, but I do sometimes get annoyed by it when it obscures browsing through the source code by stretching out the class definition. If that includes important information about the API, then I think it's worth it, but some of these comments tend to get very... sparse:

/// Gets Foo for Bar
///
/// \param [in] bar
///   Bar to get the Foo for
///
/// \return
///   Foo for bar
Foo GetFooForBar(Bar bar);

Now we eight lines of code for what should really be one or two. Would the documentation look too bad if we dropped the \param and \return thingies when we don't have anything meaningful to say there?