From cfe90c37fc750625d0e1447ed06c738afaf8a3d4 Mon Sep 17 00:00:00 2001
From: Marshall Bowers <elliott.codes@gmail.com>
Date: Fri, 1 Mar 2024 22:05:46 -0500
Subject: [PATCH] Document `release_channel` crate (#8695)

This PR documents the `release_channel` crate.

Release Notes:

- N/A
---
 crates/release_channel/src/lib.rs | 45 ++++++++++++++++++++++++++++---
 1 file changed, 41 insertions(+), 4 deletions(-)

diff --git a/crates/release_channel/src/lib.rs b/crates/release_channel/src/lib.rs
index e83ef0e069..78b17ba997 100644
--- a/crates/release_channel/src/lib.rs
+++ b/crates/release_channel/src/lib.rs
@@ -1,8 +1,12 @@
-use gpui::{AppContext, Global, SemanticVersion};
-use once_cell::sync::Lazy;
+//! Provides constructs for the Zed app version and release channel.
+
+#![deny(missing_docs)]
+
 use std::env;
 
-#[doc(hidden)]
+use gpui::{AppContext, Global, SemanticVersion};
+use once_cell::sync::Lazy;
+
 static RELEASE_CHANNEL_NAME: Lazy<String> = if cfg!(debug_assertions) {
     Lazy::new(|| {
         env::var("ZED_RELEASE_CHANNEL")
@@ -22,6 +26,7 @@ pub static RELEASE_CHANNEL: Lazy<ReleaseChannel> =
         _ => panic!("invalid release channel {}", *RELEASE_CHANNEL_NAME),
     });
 
+/// The Git commit SHA that Zed was built at.
 #[derive(Clone)]
 pub struct AppCommitSha(pub String);
 
@@ -30,11 +35,13 @@ struct GlobalAppCommitSha(AppCommitSha);
 impl Global for GlobalAppCommitSha {}
 
 impl AppCommitSha {
+    /// Returns the global [`AppCommitSha`], if one is set.
     pub fn try_global(cx: &AppContext) -> Option<AppCommitSha> {
         cx.try_global::<GlobalAppCommitSha>()
             .map(|sha| sha.0.clone())
     }
 
+    /// Sets the global [`AppCommitSha`].
     pub fn set_global(sha: AppCommitSha, cx: &mut AppContext) {
         cx.set_global(GlobalAppCommitSha(sha))
     }
@@ -44,11 +51,18 @@ struct GlobalAppVersion(SemanticVersion);
 
 impl Global for GlobalAppVersion {}
 
+/// The version of Zed.
 pub struct AppVersion;
 
 impl AppVersion {
+    /// Initializes the global [`AppVersion`].
+    ///
+    /// Attempts to read the version number from the following locations, in order:
+    /// 1. the `ZED_APP_VERSION` environment variable,
+    /// 2. the [`AppContext::app_metadata`],
+    /// 3. the passed in `pkg_version`.
     pub fn init(pkg_version: &str, cx: &mut AppContext) {
-        let version = if let Some(from_env) = env::var("ZED_APP_VERSION").ok() {
+        let version = if let Ok(from_env) = env::var("ZED_APP_VERSION") {
             from_env.parse().expect("invalid ZED_APP_VERSION")
         } else {
             cx.app_metadata()
@@ -58,17 +72,28 @@ impl AppVersion {
         cx.set_global(GlobalAppVersion(version))
     }
 
+    /// Returns the global version number.
     pub fn global(cx: &AppContext) -> SemanticVersion {
         cx.global::<GlobalAppVersion>().0
     }
 }
 
+/// A Zed release channel.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Default)]
 pub enum ReleaseChannel {
+    /// The development release channel.
+    ///
+    /// Used for local debug builds of Zed.
     #[default]
     Dev,
+
+    /// The Nightly release channel.
     Nightly,
+
+    /// The Preview release channel.
     Preview,
+
+    /// The Stable release channel.
     Stable,
 }
 
@@ -76,21 +101,25 @@ struct GlobalReleaseChannel(ReleaseChannel);
 
 impl Global for GlobalReleaseChannel {}
 
+/// Initializes the release channel.
 pub fn init(pkg_version: &str, cx: &mut AppContext) {
     AppVersion::init(pkg_version, cx);
     cx.set_global(GlobalReleaseChannel(*RELEASE_CHANNEL))
 }
 
 impl ReleaseChannel {
+    /// Returns the global [`ReleaseChannel`].
     pub fn global(cx: &AppContext) -> Self {
         cx.global::<GlobalReleaseChannel>().0
     }
 
+    /// Returns the global [`ReleaseChannel`], if one is set.
     pub fn try_global(cx: &AppContext) -> Option<Self> {
         cx.try_global::<GlobalReleaseChannel>()
             .map(|channel| channel.0)
     }
 
+    /// Returns the display name for this [`ReleaseChannel`].
     pub fn display_name(&self) -> &'static str {
         match self {
             ReleaseChannel::Dev => "Zed Dev",
@@ -100,6 +129,7 @@ impl ReleaseChannel {
         }
     }
 
+    /// Returns the programmatic name for this [`ReleaseChannel`].
     pub fn dev_name(&self) -> &'static str {
         match self {
             ReleaseChannel::Dev => "dev",
@@ -109,6 +139,7 @@ impl ReleaseChannel {
         }
     }
 
+    /// Returns the URL scheme for this [`ReleaseChannel`].
     pub fn url_scheme(&self) -> &'static str {
         match self {
             ReleaseChannel::Dev => "zed-dev://",
@@ -118,6 +149,7 @@ impl ReleaseChannel {
         }
     }
 
+    /// Returns the link prefix for this [`ReleaseChannel`].
     pub fn link_prefix(&self) -> &'static str {
         match self {
             ReleaseChannel::Dev => "https://zed.dev/dev/",
@@ -127,6 +159,7 @@ impl ReleaseChannel {
         }
     }
 
+    /// Returns the query parameter for this [`ReleaseChannel`].
     pub fn release_query_param(&self) -> Option<&'static str> {
         match self {
             Self::Dev => None,
@@ -137,6 +170,10 @@ impl ReleaseChannel {
     }
 }
 
+/// Parses the given link into a Zed link.
+///
+/// Returns a [`Some`] containing the unprefixed link if the link is a Zed link.
+/// Returns [`None`] otherwise.
 pub fn parse_zed_link(link: &str) -> Option<&str> {
     for release in [
         ReleaseChannel::Dev,