From 132b8aa5c777d9dbd0af377d2f7b222ed8706df7 Mon Sep 17 00:00:00 2001 From: Marshall Bowers Date: Tue, 9 Apr 2024 10:38:29 -0400 Subject: [PATCH] Improve extension API documentation (#10322) This PR adds some more documentation to symbols exported from the `zed_extension_api` crate. Release Notes: - N/A --- crates/extension_api/README.md | 2 +- crates/extension_api/src/extension_api.rs | 1 + crates/extension_api/src/settings.rs | 2 ++ crates/extension_api/wit/since_v0.0.6/extension.wit | 11 +++++++++++ crates/extension_api/wit/since_v0.0.6/lsp.wit | 2 ++ crates/extension_api/wit/since_v0.0.6/settings.rs | 9 +++++++++ 6 files changed, 26 insertions(+), 1 deletion(-) diff --git a/crates/extension_api/README.md b/crates/extension_api/README.md index 1f91dbe547c3a1295f27728c006eb5e0b68938ca..7e55d5fee6c3a4a24bb2a4ca2b236ed0a1e3b2fa 100644 --- a/crates/extension_api/README.md +++ b/crates/extension_api/README.md @@ -23,7 +23,7 @@ need to set your `crate-type` accordingly: ```toml [dependencies] -zed_extension_api = "0.0.1" +zed_extension_api = "0.0.6" [lib] crate-type = ["cdylib"] diff --git a/crates/extension_api/src/extension_api.rs b/crates/extension_api/src/extension_api.rs index 385537f0fdb9f5c789c56086433867c7113f2517..be3dcfc0ebc805a69f2f19ea6416ff504a62966e 100644 --- a/crates/extension_api/src/extension_api.rs +++ b/crates/extension_api/src/extension_api.rs @@ -1,5 +1,6 @@ //! The Zed Rust Extension API allows you write extensions for [Zed](https://zed.dev/) in Rust. +/// Provides access to Zed settings. pub mod settings; use core::fmt; diff --git a/crates/extension_api/src/settings.rs b/crates/extension_api/src/settings.rs index 6c56206f96d6a2d05bccdda58bff8a748fdc44b5..ffed133c4c82c3ff38b84381418965629663d286 100644 --- a/crates/extension_api/src/settings.rs +++ b/crates/extension_api/src/settings.rs @@ -6,6 +6,7 @@ use serde_json; pub use types::*; impl LanguageSettings { + /// Returns the [`LanguageSettings`] for the given language. pub fn for_worktree(language: Option<&str>, worktree: &Worktree) -> Result { let location = SettingsLocation { worktree_id: worktree.id(), @@ -18,6 +19,7 @@ impl LanguageSettings { } impl LspSettings { + /// Returns the [`LspSettings`] for the given language server. pub fn for_worktree(language_server_name: &str, worktree: &Worktree) -> Result { let location = SettingsLocation { worktree_id: worktree.id(), diff --git a/crates/extension_api/wit/since_v0.0.6/extension.wit b/crates/extension_api/wit/since_v0.0.6/extension.wit index 68b5efe8f326448dd2b759a9fb52c353edf06562..82c11ea3f6fc43fd31e00b59a978676bf3309074 100644 --- a/crates/extension_api/wit/since_v0.0.6/extension.wit +++ b/crates/extension_api/wit/since_v0.0.6/extension.wit @@ -91,26 +91,37 @@ world extension { /// Returns the workspace configuration options to pass to the language server. export language-server-workspace-configuration: func(language-server-id: string, worktree: borrow) -> result, string>; + /// A label containing some code. record code-label { /// The source code to parse with Tree-sitter. code: string, + /// The spans to display in the label. spans: list, + /// The range of the code to include when filtering. filter-range: range, } + /// A span within a code label. variant code-label-span { /// A range into the parsed code. code-range(range), + /// A span containing a code literal. literal(code-label-span-literal), } + /// A span containing a code literal. record code-label-span-literal { + /// The literal text. text: string, + /// The name of the highlight to use for this literal. highlight-name: option, } + /// A (half-open) range (`[start, end)`). record range { + /// The start of the range (inclusive). start: u32, + /// The end of the range (exclusive). end: u32, } diff --git a/crates/extension_api/wit/since_v0.0.6/lsp.wit b/crates/extension_api/wit/since_v0.0.6/lsp.wit index dae81df6d25bd5631ed13639bbf22460c7456738..19e81b6b145fe203f1c81f065285199270188277 100644 --- a/crates/extension_api/wit/since_v0.0.6/lsp.wit +++ b/crates/extension_api/wit/since_v0.0.6/lsp.wit @@ -44,11 +44,13 @@ interface lsp { other(s32), } + /// An LSP symbol. record symbol { kind: symbol-kind, name: string, } + /// The kind of an LSP symbol. variant symbol-kind { file, module, diff --git a/crates/extension_api/wit/since_v0.0.6/settings.rs b/crates/extension_api/wit/since_v0.0.6/settings.rs index 5294fac48eca06e1b1a1b1f2d62b59286f7d2bb5..5c6cae70649840d121b4effe648ceaef210bd273 100644 --- a/crates/extension_api/wit/since_v0.0.6/settings.rs +++ b/crates/extension_api/wit/since_v0.0.6/settings.rs @@ -1,20 +1,29 @@ use serde::{Deserialize, Serialize}; use std::num::NonZeroU32; +/// The settings for a particular language. #[derive(Debug, Serialize, Deserialize)] pub struct LanguageSettings { + /// How many columns a tab should occupy. pub tab_size: NonZeroU32, } +/// The settings for a particular language server. #[derive(Default, Debug, Serialize, Deserialize)] pub struct LspSettings { + /// The settings for the language server binary. pub binary: Option, + /// The initialization options to pass to the language server. pub initialization_options: Option, + /// The settings to pass to language server. pub settings: Option, } +/// The settings for a language server binary. #[derive(Debug, Serialize, Deserialize)] pub struct BinarySettings { + /// The path to the binary. pub path: Option, + /// The arguments to pass to the binary. pub arguments: Option>, }