From 9d81c11fd185a131f81841e64941859305f6c42d Mon Sep 17 00:00:00 2001
From: Mathias Fussenegger <f.mathias@zignar.net>
Date: Wed, 8 Nov 2023 14:07:56 +0100
Subject: [PATCH] Add docs for dap-session and request method

---
 doc/dap.txt         | 66 +++++++++++++++++++++++++++++++++++++++++++++
 lua/dap/session.lua |  3 +--
 2 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/doc/dap.txt b/doc/dap.txt
index 00636396..9969813f 100644
--- a/doc/dap.txt
+++ b/doc/dap.txt
@@ -983,6 +983,8 @@ session()                                                        *dap.session()*
         Returns the currently focused session or nil if no session exists or
         has focus.
 
+        See |dap-session| for a description of a session object.
+
 sessions()                                                      *dap.sessions()*
         Returns a table with the active top-level debug sessions.
         The keys are session ids and the values are the `Session` instances.
@@ -1234,5 +1236,69 @@ pick_process({opts})                                    *dap.utils.pick_process*
       filter = function(proc) return vim.endswith(proc.name, "sway") end
     })
 <
+==============================================================================
+DAP Session                                                        *dap-session*
+
+nvim-dap creates a session object per debug session. You can either get the current
+session via |dap.session()|, or get access to one via a listener (|dap-extensions|).
+
+The session object is a low level primitive, used to interact with the debug
+session. This is not indented for regular debug-client users, but rather for
+extension authors, or power users.
+
+The session contains methods - functions where the first parameter is the
+session itself. To call them, you can use the method call syntax:
+`obj:function_name()`, instead of `obj.function_name(obj)`.
+See |lua-function|.
+
+
+request({command}, {arguments}, {callback})             *dap-session:request()*
+
+    Send a request to the debug adapter.
+    See the requests section in https://microsoft.github.io/debug-adapter-protocol/specification
+    for a list of supported payloads.
+
+    Parameters:
+      {command} string      The command to execute
+      {arguments} any|nil   Arguments
+      {callback} function   Callback called with two parameters: err and result.
+
+    For example, to make a `evaluate` request, you'd use:
+
+>lua
+      local session = assert(require("dap").session(), "has active session")
+      local arguments = {
+        expression = "1 + 2"
+      }
+      session:request("evaluate", arguments, function(err, result)
+        vim.print(err or "No error")
+        vim.print(result or "No result")
+      end)
+<
+
+    The method is coroutine aware. If it is running inside a coroutine you can
+    omit the callback and it will default to resume the coroutine with the
+    result.
+
+    An example:
+
+>lua
+      local session = assert(require("dap").session(), "has active session")
+      local arguments = {
+        expression = "1 + 2"
+      }
+      coroutine.wrap(function()
+        local err, result = session:request("evaluate", arguments)
+        vim.print(err or "No error")
+        vim.print(result or "No result")
+      end)()
+<
+
+    This is convenient if you want to make multiple requests as it helps
+    prevent callback nesting.
+
+    Note that `coroutine.wrap` doesn't propagate errors but you could setup
+    error handling via |xpcall()|
+
 
 vim:ft=help
diff --git a/lua/dap/session.lua b/lua/dap/session.lua
index 3be22c2c..adfe28d7 100644
--- a/lua/dap/session.lua
+++ b/lua/dap/session.lua
@@ -1664,8 +1664,7 @@ end
 --- Send a request to the debug adapter
 ---@param command string command to execute
 ---@param arguments any|nil object containing arguments for the command
----@param callback fun(err: table, result: any)|nil
---  callback called with the response result.
+---@param callback fun(err: table, result: any)|nil called with the response result.
 --- If nil and running within a coroutine the function will yield the result
 function Session:request(command, arguments, callback)
   local payload = {