Document debugger

debugger/src/debugger.rs

@@ -17,14 +17,18 @@ use transport::{
 };
 
 use crate::{
-    internals::{DebuggerInternals, FileSource},
+    internals::DebuggerInternals,
     state::{self, DebuggerState},
     types::{self, EvaluateResult},
     Event,
 };
 
+/// How to launch a debugging session
 pub enum InitialiseArguments {
+    /// Launch a new process with a debugger and connect to the session immediately
     Launch(state::LaunchArguments),
+
+    /// Attach to a running process
     Attach(state::AttachArguments),
 }
 
@@ -63,12 +67,16 @@ where
     })
 }
 
+/// Represents a debugging session
 pub struct Debugger {
     internals: Arc<Mutex<DebuggerInternals>>,
     rx: crossbeam_channel::Receiver<Event>,
 }
 
 impl Debugger {
+    /// Connect to an existing DAP session on the given port.
+    ///
+    /// Takes [`InitialiseArguments`] for configuration of the debugging session
     #[tracing::instrument(skip(initialise_arguments))]
     pub fn on_port(
         port: u16,
@@ -132,15 +140,21 @@ impl Debugger {
             rx: internals_rx,
         })
     }
+
+    /// Create a new debugging session on the default DAP port (5678)
+    ///
+    /// Note: the debugging session does not start until [`Debugger::start`] is called
     #[tracing::instrument(skip(initialise_arguments))]
     pub fn new(initialise_arguments: impl Into<InitialiseArguments>) -> eyre::Result<Self> {
         Self::on_port(DEFAULT_DAP_PORT, initialise_arguments)
     }
 
+    /// Return a [`crossbeam_channel::Receiver<Event>`] to subscribe to debugging events
     pub fn events(&self) -> crossbeam_channel::Receiver<Event> {
         self.rx.clone()
     }
 
+    /// Add a breakpoint for the current debugging session
     pub fn add_breakpoint(
         &self,
         breakpoint: &types::Breakpoint,
@@ -149,7 +163,8 @@ impl Debugger {
         internals.add_breakpoint(breakpoint)
     }
 
-    pub fn launch(&self) -> eyre::Result<()> {
+    /// Launch a debugging session
+    pub fn start(&self) -> eyre::Result<()> {
         let mut internals = self.internals.lock().unwrap();
         let _ = internals
             .client
@@ -159,6 +174,7 @@ impl Debugger {
         Ok(())
     }
 
+    /// Perform a code/variable evaluation within a debugging session
     pub fn evaluate(
         &self,
         input: &str,
@@ -268,18 +284,11 @@ impl Debugger {
         Ok(())
     }
 
-    pub fn with_current_source<F>(&self, f: F)
-    where
-        F: Fn(Option<&FileSource>),
-    {
-        let internals = self.internals.lock().unwrap();
-        f(internals.current_source.as_ref())
-    }
-
     fn execute(&self, body: requests::RequestBody) -> eyre::Result<()> {
         self.internals.lock().unwrap().client.execute(body)
     }
 
+    /// Pause the debugging session waiting for a specific event, where the predicate returns true
     pub fn wait_for_event<F>(&self, pred: F) -> Event
     where
         F: Fn(&Event) -> bool,
@@ -301,6 +310,7 @@ impl Debugger {
         }
     }
 
+    /// Change the current scope to a new stack frame
     pub fn change_scope(&self, stack_frame_id: StackFrameId) -> eyre::Result<()> {
         self.internals
             .lock()

debugger/src/lib.rs

@@ -1,11 +1,12 @@
+//! High level Debugger implementation
 mod debugger;
 mod internals;
 mod persistence;
 pub(crate) mod state;
 mod types;
 pub mod utils;
 
-pub use debugger::Debugger;
+pub use debugger::{Debugger, InitialiseArguments};
 pub use internals::FileSource;
 pub use state::{AttachArguments, Event, Language, LaunchArguments};
 pub use types::{Breakpoint, EvaluateResult, PausedFrame};

debugger/src/state.rs

@@ -57,6 +57,7 @@ impl<'a> From<&'a DebuggerState> for Event {
     }
 }
 
+/// Languages supported by the debugger crate
 #[derive(Debug, Clone, Copy)]
 pub enum Language {
     DebugPy,
@@ -75,11 +76,19 @@ impl FromStr for Language {
     }
 }
 
+/// Arguments for attaching to a running process
 #[derive(Debug)]
 pub struct AttachArguments {
+    /// Working directory for the debugging session
     pub working_directory: PathBuf,
+
+    /// Debugger port to connect to (defaults to 5678)
     pub port: Option<u16>,
+
+    /// Programming language of the debugee
     pub language: Language,
+
+    /// Custom mappings from the running code (e.g. in a Docker container) to local source checkout
     pub path_mappings: Option<Vec<requests::PathMapping>>,
 }
 
@@ -97,9 +106,15 @@ impl AttachArguments {
     }
 }
 
+/// Arguments for launching a new process
 pub struct LaunchArguments {
+    /// Program to run
     pub program: PathBuf,
+
+    /// Current working directory for the launched process
     pub working_directory: Option<PathBuf>,
+
+    /// Language used to create the process
     pub language: Language,
 }
 

debugger/tests/debugger.rs

@@ -79,7 +79,7 @@ fn test_remote_attach() -> eyre::Result<()> {
             ..Default::default()
         })
         .context("adding breakpoint")?;
-    debugger.launch().context("launching debugee")?;
+    debugger.start().context("launching debugee")?;
 
     wait_for_event("running event", &drx, |e| {
         matches!(e, debugger::Event::Running { .. })
@@ -151,7 +151,7 @@ fn test_debugger() -> eyre::Result<()> {
             ..Default::default()
         })
         .context("adding breakpoint")?;
-    debugger.launch().context("launching debugee")?;
+    debugger.start().context("launching debugee")?;
 
     wait_for_event("running event", &drx, |e| {
         matches!(e, debugger::Event::Running { .. })

gui/src/main.rs

@@ -241,7 +241,7 @@ impl DebuggerApp {
         }
 
         tracing::debug!("launching debugee");
-        debugger.launch().context("launching debugee")?;
+        debugger.start().context("launching debugee")?;
 
         let temp_state = DebuggerAppState {
             state: State::Initialising,

gui2/src/lib.rs

@@ -181,7 +181,7 @@ impl DebuggerApp {
         }
 
         tracing::debug!("launching debugee");
-        debugger.launch().context("launching debugee")?;
+        debugger.start().context("launching debugee")?;
 
         Ok(Self {
             state: AppState::Running {