Improve extension API documentation (#10210)

This PR adds more documentation for various constructs in the
`zed_extension_api` crate.

`wit_bindgen` is able to generate doc comments on the Rust constructs
using the the doc comments in the WIT files, so we're able to leverage
that for the majority of the constructs that we expose.

Release Notes:

- N/A

crates/extension_api/src/extension_api.rs

@@ -1,3 +1,5 @@
+//! The Zed Rust Extension API allows you write extensions for [Zed](https://zed.dev/) in Rust.
+
 use core::fmt;
 
 use wit::*;
@@ -8,10 +10,10 @@ use wit::*;
 // that we may want to shadow to provide a cleaner Rust API.
 pub use wit::{
     current_platform, download_file, latest_github_release, make_file_executable, node_binary_path,
-    npm_install_package, npm_package_installed_version, npm_package_latest_version,
-    zed::extension::lsp, Architecture, CodeLabel, CodeLabelSpan, CodeLabelSpanLiteral, Command,
-    DownloadedFileType, EnvVars, GithubRelease, GithubReleaseAsset, GithubReleaseOptions,
-    LanguageServerInstallationStatus, Os, Range, Worktree,
+    npm_install_package, npm_package_installed_version, npm_package_latest_version, Architecture,
+    CodeLabel, CodeLabelSpan, CodeLabelSpanLiteral, Command, DownloadedFileType, EnvVars,
+    GithubRelease, GithubReleaseAsset, GithubReleaseOptions, LanguageServerInstallationStatus, Os,
+    Range, Worktree,
 };
 
 // Undocumented WIT re-exports.
@@ -21,6 +23,14 @@ pub use wit::{
 #[doc(hidden)]
 pub use wit::Guest;
 
+/// Constructs for interacting with language servers over the
+/// Language Server Protocol (LSP).
+pub mod lsp {
+    pub use crate::wit::zed::extension::lsp::{
+        Completion, CompletionKind, InsertTextFormat, Symbol, SymbolKind,
+    };
+}
+
 /// A result returned from a Zed extension.
 pub type Result<T, E = String> = core::result::Result<T, E>;
 
@@ -75,6 +85,9 @@ pub trait Extension: Send + Sync {
     }
 }
 
+/// Registers the provided type as a Zed extension.
+///
+/// The type must implement the [`Extension`] trait.
 #[macro_export]
 macro_rules! register_extension {
     ($extension_type:ty) => {
@@ -165,6 +178,7 @@ impl wit::Guest for Component {
     }
 }
 
+/// The ID of a language server.
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone)]
 pub struct LanguageServerId(String);
 

crates/extension_api/wit/since_v0.0.6/extension.wit

@@ -5,56 +5,84 @@ world extension {
 
     use lsp.{completion, symbol};
 
+    /// Initializes the extension.
     export init-extension: func();
 
+    /// A GitHub release.
     record github-release {
+        /// The version of the release.
         version: string,
+        /// The list of assets attached to the release.
         assets: list<github-release-asset>,
     }
 
+    /// An asset from a GitHub release.
     record github-release-asset {
+        /// The name of the asset.
         name: string,
+        /// The download URL for the asset.
         download-url: string,
     }
 
+    /// The options used to filter down GitHub releases.
     record github-release-options {
+        /// Whether releases without assets should be included.
         require-assets: bool,
+        /// Whether pre-releases should be included.
         pre-release: bool,
     }
 
+    /// An operating system.
     enum os {
+        /// macOS.
         mac,
+        /// Linux.
         linux,
+        /// Windows.
         windows,
     }
 
+    /// A platform architecture.
     enum architecture {
+        /// AArch64 (e.g., Apple Silicon).
         aarch64,
+        /// x86.
         x86,
+        /// x86-64.
         x8664,
     }
 
+    /// The type of a downloaded file.
     enum downloaded-file-type {
+        /// A gzipped file (`.gz`).
         gzip,
+        /// A gzipped tar archive (`.tar.gz`).
         gzip-tar,
+        /// A ZIP file (`.zip`).
         zip,
+        /// An uncompressed file.
         uncompressed,
     }
 
+    /// The installation status for a language server.
     variant language-server-installation-status {
+        /// The language server has no installation status.
         none,
+        /// The language server is being downloaded.
         downloading,
+        /// The language server is checking for updates.
         checking-for-update,
+        /// The language server installation failed for specified reason.
         failed(string),
     }
 
-    /// Gets the current operating system and architecture
+    /// Returns operating system and architecture for the current platform.
     import current-platform: func() -> tuple<os, architecture>;
 
-    /// Get the path to the node binary used by Zed.
+    /// Returns the path to the Node binary used by Zed.
     import node-binary-path: func() -> result<string, string>;
 
-    /// Gets the latest version of the given NPM package.
+    /// Returns the latest version of the given NPM package.
     import npm-package-latest-version: func(package-name: string) -> result<string, string>;
 
     /// Returns the installed version of the given NPM package, if it exists.
@@ -63,11 +91,13 @@ world extension {
     /// Installs the specified NPM package.
     import npm-install-package: func(package-name: string, version: string) -> result<_, string>;
 
-    /// Gets the latest release for the given GitHub repository.
+    /// Returns the latest release for the given GitHub repository.
     import latest-github-release: func(repo: string, options: github-release-options) -> result<github-release, string>;
 
-    /// Downloads a file from the given url, and saves it to the given path within the extension's
-    /// working directory. Extracts the file according to the given file type.
+    /// Downloads a file from the given URL and saves it to the given path within the extension's
+    /// working directory.
+    ///
+    /// The file will be extracted according to the given file type.
     import download-file: func(url: string, file-path: string, file-type: downloaded-file-type) -> result<_, string>;
 
     /// Makes the file at the given path executable.
@@ -76,21 +106,35 @@ world extension {
     /// Updates the installation status for the given language server.
     import set-language-server-installation-status: func(language-server-name: string, status: language-server-installation-status);
 
+    /// A list of environment variables.
     type env-vars = list<tuple<string, string>>;
 
+    /// A command.
     record command {
+        /// The command to execute.
         command: string,
+        /// The arguments to pass to the command.
         args: list<string>,
+        /// The environment variables to set for the command.
         env: env-vars,
     }
 
+    /// A Zed worktree.
     resource worktree {
+        /// Returns the textual contents of the specified file in the worktree.
         read-text-file: func(path: string) -> result<string, string>;
+        /// Returns the path to the given binary name, if one is present on the `$PATH`.
         which: func(binary-name: string) -> option<string>;
+        /// Returns the current shell environment.
         shell-env: func() -> env-vars;
     }
 
+    /// Returns the command used to start up the language server.
     export language-server-command: func(language-server-id: string, worktree: borrow<worktree>) -> result<command, string>;
+
+    /// Returns the initialization options to pass to the language server on startup.
+    ///
+    /// The initialization options are represented as a JSON string.
     export language-server-initialization-options: func(language-server-id: string, worktree: borrow<worktree>) -> result<option<string>, string>;
 
     record code-label {

crates/extension_api/wit/since_v0.0.6/lsp.wit

@@ -7,6 +7,7 @@ interface lsp {
         insert-text-format: option<insert-text-format>,
     }
 
+    /// The kind of an LSP completion.
     variant completion-kind {
         text,
         method,
@@ -36,6 +37,7 @@ interface lsp {
         other(s32),
     }
 
+    /// Defines how to interpret the insert text in a completion item.
     variant insert-text-format {
         plain-text,
         snippet,