docs(vimdoc): add rustaceanvim.dap section

README.md

@@ -207,7 +207,6 @@ vim.keymap.set(
   You can call them with `require('dap').continue()` or `:DapContinue` once
   they have been loaded. The feature can be disabled by setting
   `vim.g.rustaceanvim.dap.autoload_configurations = false`.
-  It is disabled by default in neovim 0.9, as it can block the UI.
 
   - `:RustLsp debuggables` will only load debug configurations
     created by `rust-analyzer`.

doc/rustaceanvim.txt

@@ -1,14 +1,15 @@
 ==============================================================================
 Table of Contents                                        *rustaceanvim.contents*
 
-Introduction ··························································· |intro|
+Introduction ·············································· |rustaceanvim.intro|
  ································································ |rustaceanvim|
 plugin configuration ····································· |rustaceanvim.config|
 LSP configuration utility ························· |rustaceanvim.config.server|
  ························································ |rustaceanvim.neotest|
+ ···························································· |rustaceanvim.dap|
 
 ==============================================================================
-Introduction                                                             *intro*
+Introduction                                                *rustaceanvim.intro*
 
 This plugin automatically configures the `rust-analyzer` builtin LSP client
 and integrates with other rust tools.
@@ -474,4 +475,31 @@ Note: If you use this adapter, do not add the neotest-rust adapter
 (another plugin).
 
 
+==============================================================================
+                                                              *rustaceanvim.dap*
+
+
+ The DAP integration requires `nvim-dap` https://github.com/mfussenegger/nvim-dap
+ (Please read the plugin's documentation, see |dap-adapter|)
+ and a debug adapter (e.g. `lldb` https://lldb.llvm.org/
+ or `codelldb` https://github.com/vadimcn/codelldb).
+
+ By default, this plugin will silently attempt to autoload |dap-configuration|s
+ when the LSP client attaches.
+ You can call them with `require('dap').continue()` or `:DapContinue` once
+ they have been loaded. The feature can be disabled by setting
+ `vim.g.rustaceanvim.dap.autoload_configurations = false`.
+
+ - `:RustLsp debuggables` will only load debug configurations
+   created by `rust-analyzer`.
+ - `require('dap').continue()` will load all Rust debug configurations,
+   including those specified in a `.vscode/launch.json`
+   (see |dap-launch.json|)
+
+ IMPORTANT: Note that rustaceanvim may only be able to load DAP configurations
+ when rust-analyzer has finished initializing (which may be after
+ the client attaches, in large projects). This means that the
+ DAP configurations may not be loaded immediately upon startup.
+
+
 vim:tw=78:ts=8:noet:ft=help:norl:

flake.nix

@@ -113,6 +113,13 @@
             luacheck.enable = true;
             editorconfig-checker.enable = true;
             markdownlint.enable = true;
+            docgen = {
+              enable = true;
+              name = "docgen";
+              entry = "${docgen}/bin/docgen";
+              files = "\\.(lua)$";
+              pass_filenames = false;
+            };
           };
         };
 
@@ -130,6 +137,7 @@
               luacheck
               editorconfig-checker
               markdownlint-cli
+              docgen
             ]
             ++ oa.buildInputs;
           doCheck = false;

lua/rustaceanvim/dap.lua

@@ -1,3 +1,30 @@
+---@mod rustaceanvim.dap
+---@brief [[
+---
+--- The DAP integration requires `nvim-dap` https://github.com/mfussenegger/nvim-dap
+--- (Please read the plugin's documentation, see |dap-adapter|)
+--- and a debug adapter (e.g. `lldb` https://lldb.llvm.org/
+--- or `codelldb` https://github.com/vadimcn/codelldb).
+---
+--- By default, this plugin will silently attempt to autoload |dap-configuration|s
+--- when the LSP client attaches.
+--- You can call them with `require('dap').continue()` or `:DapContinue` once
+--- they have been loaded. The feature can be disabled by setting
+--- `vim.g.rustaceanvim.dap.autoload_configurations = false`.
+---
+--- - `:RustLsp debuggables` will only load debug configurations
+---   created by `rust-analyzer`.
+--- - `require('dap').continue()` will load all Rust debug configurations,
+---   including those specified in a `.vscode/launch.json`
+---   (see |dap-launch.json|)
+---
+--- IMPORTANT: Note that rustaceanvim may only be able to load DAP configurations
+--- when rust-analyzer has finished initializing (which may be after
+--- the client attaches, in large projects). This means that the
+--- DAP configurations may not be loaded immediately upon startup.
+---
+---@brief ]]
+
 local config = require('rustaceanvim.config.internal')
 local shell = require('rustaceanvim.shell')
 local types = require('rustaceanvim.types.internal')
@@ -67,6 +94,7 @@ local function get_rustc_sysroot(callback)
   end)
 end
 
+---@package
 ---@alias rustaceanvim.dap.SourceMap {[string]: string}
 
 ---@param tbl { [string]: string }
@@ -239,6 +267,7 @@ local function handle_configured_options(adapter, args, verbose)
   end
 end
 
+---@package
 ---@param args rustaceanvim.RARunnableArgs
 ---@param verbose? boolean
 ---@param callback? fun(config: rustaceanvim.dap.client.Config)

lua/rustaceanvim/init.lua

@@ -1,6 +1,6 @@
 ---@toc rustaceanvim.contents
 
----@mod intro Introduction
+---@mod rustaceanvim.intro Introduction
 ---@brief [[
 ---This plugin automatically configures the `rust-analyzer` builtin LSP client
 ---and integrates with other rust tools.

nix/docgen.nix

@@ -6,6 +6,6 @@ pkgs.writeShellApplication {
   ];
   text = ''
     mkdir -p doc
-    lemmy-help lua/rustaceanvim/{init,config/init,config/server,neotest/init}.lua > doc/rustaceanvim.txt
+    lemmy-help lua/rustaceanvim/{init,config/init,config/server,neotest/init,dap}.lua > doc/rustaceanvim.txt
   '';
 }