Improve extension API documentation (#10322)

Marshall Bowers created 2 years ago

This PR adds some more documentation to symbols exported from the
`zed_extension_api` crate.

Release Notes:

- N/A

Change summary

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(-)

Detailed changes

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"]

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;

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<Self> {
         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<Self> {
         let location = SettingsLocation {
             worktree_id: worktree.id(),

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<worktree>) -> result<option<string>, 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<code-label-span>,
+        /// 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<string>,
     }
 
+    /// A (half-open) range (`[start, end)`).
     record range {
+        /// The start of the range (inclusive).
         start: u32,
+        /// The end of the range (exclusive).
         end: u32,
     }
 

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,

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<BinarySettings>,
+    /// The initialization options to pass to the language server.
     pub initialization_options: Option<serde_json::Value>,
+    /// The settings to pass to language server.
     pub settings: Option<serde_json::Value>,
 }
 
+/// The settings for a language server binary.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct BinarySettings {
+    /// The path to the binary.
     pub path: Option<String>,
+    /// The arguments to pass to the binary.
     pub arguments: Option<Vec<String>>,
 }