docs(language_server): docs for Backend struct

Author: Sysix

crates/oxc_language_server/src/backend.rs

@@ -29,6 +29,10 @@ use crate::{
     worker::WorkspaceWorker,
 };
 
+/// The Backend implements the LanguageServer trait to handle LSP requests and notifications.
+///
+/// It manages multiple WorkspaceWorkers, each corresponding to a workspace folder.
+/// Depending on the client's capabilities, it can dynamically register features and start up other services.
 pub struct Backend {
     client: Client,
     // Each Workspace has it own worker with Linter (and in the future the formatter).
@@ -39,11 +43,21 @@ pub struct Backend {
     // 1. `initialize` request with workspace folders
     // 2. `workspace/didChangeWorkspaceFolders` request
     workspace_workers: Arc<RwLock<Vec<WorkspaceWorker>>>,
+    // Capabilities of the language server, set once during `initialize` request.
+    // Depending on the client capabilities, the server supports different capabilities.
     capabilities: OnceCell<Capabilities>,
+    // A simple in-memory file system to store the content of open files.
+    // The client will send the content of in-memory files on `textDocument/didOpen` and `textDocument/didChange`.
+    // This is only needed when the client supports `textDocument/formatting` request,
     file_system: Arc<RwLock<LSPFileSystem>>,
 }
 
 impl LanguageServer for Backend {
+    /// Initialize the language server with the given parameters.
+    /// This method sets up workspace workers, capabilities, and starts the
+    /// [WorkspaceWorker]s if the client sent the configuration with initialization options.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize>
     #[expect(deprecated)] // `params.root_uri` is deprecated, we are only falling back to it if no workspace folder is provided
     async fn initialize(&self, params: InitializeParams) -> Result<InitializeResult> {
         let server_version = env!("CARGO_PKG_VERSION");
@@ -134,6 +148,11 @@ impl LanguageServer for Backend {
         })
     }
 
+    /// The `initialized` notification is sent from the client to the server after the `initialize` request.
+    /// This method registers dynamic capabilities like file watchers and formatting if the client supports it.
+    /// It also starts the [WorkspaceWorker]s if they did not start during initialization.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialized>
     async fn initialized(&self, _params: InitializedParams) {
         debug!("oxc initialized.");
         let Some(capabilities) = self.capabilities.get() else {
@@ -209,6 +228,10 @@ impl LanguageServer for Backend {
         }
     }
 
+    /// The `shutdown` request is sent from the client to the server to ask for a graceful shutdown.
+    /// This method clears all diagnostics and the in-memory file system if dynamic formatting is enabled.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#shutdown>
     async fn shutdown(&self) -> Result<()> {
         self.clear_all_diagnostics().await;
         if self.capabilities.get().is_some_and(|option| option.dynamic_formatting) {
@@ -217,6 +240,12 @@ impl LanguageServer for Backend {
         Ok(())
     }
 
+    /// The `workspace/didChangeConfiguration` notification is sent from the client to the server
+    /// when the server configuration has changed in the client.
+    /// This method updates the configuration of each [WorkspaceWorker] and restarts them if necessary.
+    /// It also manages dynamic registrations for file watchers and formatting based on the new configuration.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_didChangeConfiguration>
     async fn did_change_configuration(&self, params: DidChangeConfigurationParams) {
         let workers = self.workspace_workers.read().await;
         let new_diagnostics: papaya::HashMap<String, Vec<Diagnostic>, FxBuildHasher> =
@@ -354,6 +383,10 @@ impl LanguageServer for Backend {
         }
     }
 
+    /// The `workspace/didChangeWatchedFiles` notification is sent from the client to the server.
+    /// This notification is sent when a configuration file of a tool changes (example: `.oxlintrc.json`).
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_didChangeWatchedFiles>
     async fn did_change_watched_files(&self, params: DidChangeWatchedFilesParams) {
         let workers = self.workspace_workers.read().await;
         // ToDo: what if an empty changes flag is passed?
@@ -393,6 +426,13 @@ impl LanguageServer for Backend {
         self.publish_all_diagnostics(x).await;
     }
 
+    /// The `workspace/didChangeWorkspaceFolders` notification is sent from the client to the server.
+    /// The server will start new [WorkspaceWorker]s for added workspace folders
+    /// and stop and remove [WorkspaceWorker]s for removed workspace folders including:
+    /// - clearing diagnostics
+    /// - unregistering file watchers
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_didChangeWorkspaceFolders>
     async fn did_change_workspace_folders(&self, params: DidChangeWorkspaceFoldersParams) {
         let mut workers = self.workspace_workers.write().await;
         let mut cleared_diagnostics = vec![];
@@ -471,6 +511,10 @@ impl LanguageServer for Backend {
         }
     }
 
+    /// The `textDocument/didSave` notification is sent from the client to the server.
+    /// It will remove the in-memory file content, because the file is saved to disk.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_didSave>
     async fn did_save(&self, params: DidSaveTextDocumentParams) {
         debug!("oxc server did save");
         let uri = &params.text_document.uri;
@@ -495,8 +539,10 @@ impl LanguageServer for Backend {
         }
     }
 
-    /// When the document changed, it may not be written to disk, so we should
-    /// get the file context from the language client
+    /// The `textDocument/didChange` notification is sent from the client to the server.
+    /// It will update the in-memory file content if the client supports dynamic formatting.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_didChange>
     async fn did_change(&self, params: DidChangeTextDocumentParams) {
         let uri = &params.text_document.uri;
         let workers = self.workspace_workers.read().await;
@@ -522,6 +568,10 @@ impl LanguageServer for Backend {
         }
     }
 
+    /// The `textDocument/didOpen` notification is sent from the client to the server.
+    /// It will add the in-memory file content if the client supports dynamic formatting.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_didOpen>
     async fn did_open(&self, params: DidOpenTextDocumentParams) {
         let uri = &params.text_document.uri;
         let workers = self.workspace_workers.read().await;
@@ -548,6 +598,10 @@ impl LanguageServer for Backend {
         }
     }
 
+    /// The `textDocument/didClose` notification is sent from the client to the server.
+    /// It will remove the in-memory file content if the client supports dynamic formatting.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_didClose>
     async fn did_close(&self, params: DidCloseTextDocumentParams) {
         let uri = &params.text_document.uri;
         let workers = self.workspace_workers.read().await;
@@ -560,6 +614,10 @@ impl LanguageServer for Backend {
         worker.remove_diagnostics(&params.text_document.uri).await;
     }
 
+    /// The `textDocument/codeAction` request is sent from the client to the server.
+    /// It will return code actions or commands for the given range.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction>
     async fn code_action(&self, params: CodeActionParams) -> Result<Option<CodeActionResponse>> {
         let uri = &params.text_document.uri;
         let workers = self.workspace_workers.read().await;
@@ -582,6 +640,11 @@ impl LanguageServer for Backend {
         Ok(Some(code_actions))
     }
 
+    /// The `workspace/executeCommand` request is sent from the client to the server.
+    /// It will execute the given command with the provided arguments.
+    /// Currently, only the `fixAll` command is supported.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand>
     async fn execute_command(
         &self,
         params: ExecuteCommandParams,
@@ -618,6 +681,10 @@ impl LanguageServer for Backend {
         Err(Error::invalid_request())
     }
 
+    /// The `textDocument/formatting` request is sent from the client to the server.
+    /// It will return text edits to format the document if formatting is enabled for the workspace.
+    ///
+    /// @link <https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting>
     async fn formatting(&self, params: DocumentFormattingParams) -> Result<Option<Vec<TextEdit>>> {
         let uri = &params.text_document.uri;
         let workers = self.workspace_workers.read().await;
@@ -629,6 +696,10 @@ impl LanguageServer for Backend {
 }
 
 impl Backend {
+    /// Create a new Backend with the given client.
+    /// The Backend will manage multiple [WorkspaceWorker]s and their configurations.
+    /// It also holds the capabilities of the language server and an in-memory file system.
+    /// The client is used to communicate with the LSP client.
     pub fn new(client: Client) -> Self {
         Self {
             client,
@@ -670,7 +741,7 @@ impl Backend {
         options
     }
 
-    // clears all diagnostics for workspace folders
+    /// clears all diagnostics for workspace folders
     async fn clear_all_diagnostics(&self) {
         let mut cleared_diagnostics = vec![];
         let workers = &*self.workspace_workers.read().await;
@@ -680,6 +751,7 @@ impl Backend {
         self.publish_all_diagnostics(&cleared_diagnostics).await;
     }
 
+    /// Publish diagnostics for all files.
     async fn publish_all_diagnostics(&self, result: &[(String, Vec<Diagnostic>)]) {
         join_all(result.iter().map(|(path, diagnostics)| {
             self.client.publish_diagnostics(Uri::from_str(path).unwrap(), diagnostics.clone(), None)