Add docs for GraphQL DAP endpoints (#1636)

Note that the DAP GraphQL API needs updates after #1600, as some new
things (like clearing breakpoints) are available. That will be a
follow-up.

CHANGELOG.md

@@ -23,6 +23,7 @@ Description of the upcoming release here.
 - [#1579](https://github.com/FuelLabs/fuel-core/pull/1579): The change extracts the off-chain-related logic from the executor and moves it to the GraphQL off-chain worker. It creates two new concepts - Off-chain and On-chain databases where the GraphQL worker has exclusive ownership of the database and may modify it without intersecting with the On-chain database.
 - [#1577](https://github.com/FuelLabs/fuel-core/pull/1577): Moved insertion of sealed blocks into the `BlockImporter` instead of the executor.
 - [#1601](https://github.com/FuelLabs/fuel-core/pull/1601): Fix formatting in docs and check that `cargo doc` passes in the CI.
+- [#1636](https://github.com/FuelLabs/fuel-core/pull/1636): Add more docs to GraphQL DAP API.
 
 #### Breaking
 - [#1639](https://github.com/FuelLabs/fuel-core/pull/1639): Make Merkle metadata, i.e. `SparseMerkleMetadata` and `DenseMerkleMetadata` type version-able enums

crates/client/assets/schema.sdl

@@ -83,6 +83,9 @@ type BlockEdge {
 scalar BlockId
 
 
+"""
+Breakpoint, defined as a tuple of contract ID and relative PC offset inside it
+"""
 input Breakpoint {
 	contract: ContractId!
 	pc: U64!
@@ -578,13 +581,42 @@ type MessageStatus {
 }
 
 type Mutation {
+	"""
+	Initialize a new debugger session, returning its ID.
+	A new VM instance is spawned for each session.
+	The session is run in a separate database transaction,
+	on top of the most recent node state.
+	"""
 	startSession: ID!
+	"""
+	End debugger session.
+	"""
 	endSession(id: ID!): Boolean!
+	"""
+	Reset the VM instance to the initial state.
+	"""
 	reset(id: ID!): Boolean!
+	"""
+	Execute a single fuel-asm instruction.
+	"""
 	execute(id: ID!, op: String!): Boolean!
+	"""
+	Set single-stepping mode for the VM instance.
+	"""
 	setSingleStepping(id: ID!, enable: Boolean!): Boolean!
+	"""
+	Set a breakpoint for a VM instance.
+	"""
 	setBreakpoint(id: ID!, breakpoint: Breakpoint!): Boolean!
+	"""
+	Run a single transaction in given session until it
+	hits a breakpoint or completes.
+	"""
 	startTx(id: ID!, txJson: String!): RunResult!
+	"""
+	Resume execution of the VM instance after a breakpoint.
+	Runs until the next breakpoint or until the transaction completes.
+	"""
 	continueTx(id: ID!): RunResult!
 	"""
 	Execute a dry-run of the transaction using a fork of current state, no changes are committed.
@@ -704,7 +736,13 @@ type ProgramState {
 }
 
 type Query {
+	"""
+	Read register value by index.
+	"""
 	register(id: ID!, register: U32!): U64!
+	"""
+	Read read a range of memory bytes.
+	"""
 	memory(id: ID!, start: U32!, size: U32!): String!
 	balance(owner: Address!, assetId: AssetId!): Balance!
 	balances(filter: BalanceFilterInput!, first: Int, after: String, last: Int, before: String): BalanceConnection!

crates/fuel-core/src/schema/dap.rs

@@ -217,6 +217,7 @@ fn require_debug(ctx: &Context<'_>) -> async_graphql::Result<()> {
 
 #[Object]
 impl DapQuery {
+    /// Read register value by index.
     async fn register(
         &self,
         ctx: &Context<'_>,
@@ -232,6 +233,7 @@ impl DapQuery {
             .map(|val| val.into())
     }
 
+    /// Read read a range of memory bytes.
     async fn memory(
         &self,
         ctx: &Context<'_>,
@@ -251,6 +253,10 @@ impl DapQuery {
 
 #[Object]
 impl DapMutation {
+    /// Initialize a new debugger session, returning its ID.
+    /// A new VM instance is spawned for each session.
+    /// The session is run in a separate database transaction,
+    /// on top of the most recent node state.
     async fn start_session(&self, ctx: &Context<'_>) -> async_graphql::Result<ID> {
         require_debug(ctx)?;
         trace!("Initializing new interpreter");
@@ -268,6 +274,7 @@ impl DapMutation {
         Ok(id)
     }
 
+    /// End debugger session.
     async fn end_session(
         &self,
         ctx: &Context<'_>,
@@ -281,6 +288,7 @@ impl DapMutation {
         Ok(existed)
     }
 
+    /// Reset the VM instance to the initial state.
     async fn reset(&self, ctx: &Context<'_>, id: ID) -> async_graphql::Result<bool> {
         require_debug(ctx)?;
         let db = ctx.data_unchecked::<Database>();
@@ -295,6 +303,7 @@ impl DapMutation {
         Ok(true)
     }
 
+    /// Execute a single fuel-asm instruction.
     async fn execute(
         &self,
         ctx: &Context<'_>,
@@ -316,6 +325,7 @@ impl DapMutation {
         Ok(result)
     }
 
+    /// Set single-stepping mode for the VM instance.
     async fn set_single_stepping(
         &self,
         ctx: &Context<'_>,
@@ -335,14 +345,15 @@ impl DapMutation {
         Ok(enable)
     }
 
+    /// Set a breakpoint for a VM instance.
     async fn set_breakpoint(
         &self,
         ctx: &Context<'_>,
         id: ID,
         breakpoint: gql_types::Breakpoint,
     ) -> async_graphql::Result<bool> {
         require_debug(ctx)?;
-        trace!("Continue execution of VM {:?}", id);
+        trace!("Set breakpoint for VM {:?}", id);
 
         let mut locked = ctx.data_unchecked::<GraphStorage>().lock().await;
         let vm = locked
@@ -354,6 +365,8 @@ impl DapMutation {
         Ok(true)
     }
 
+    /// Run a single transaction in given session until it
+    /// hits a breakpoint or completes.
     async fn start_tx(
         &self,
         ctx: &Context<'_>,
@@ -426,6 +439,8 @@ impl DapMutation {
         }
     }
 
+    /// Resume execution of the VM instance after a breakpoint.
+    /// Runs until the next breakpoint or until the transaction completes.
     async fn continue_tx(
         &self,
         ctx: &Context<'_>,
@@ -492,6 +507,7 @@ mod gql_types {
 
     use fuel_core_types::fuel_vm::Breakpoint as FuelBreakpoint;
 
+    /// Breakpoint, defined as a tuple of contract ID and relative PC offset inside it
     #[derive(Debug, Clone, Copy, InputObject)]
     pub struct Breakpoint {
         contract: ContractId,