gpui: Further docs refinement & moved some reexports into 'private' m…

…odule (zed-industries#3935)

This commit mostly fixes invalid URLs in docstrings. It also
encapsulates crates we reexport (serde stuff + linkme) into a public
module named "private" in order to reduce the API surfaced through docs.
Moreover, I fixed up a bunch of crates that were pulling serde_json in
through gpui explicitly instead of using Cargo manifest.

Release Notes:
- N/A

crates/ai/src/providers/open_ai/embedding.rs

@@ -1,8 +1,8 @@
 use anyhow::{anyhow, Result};
 use async_trait::async_trait;
 use futures::AsyncReadExt;
+use gpui::AppContext;
 use gpui::BackgroundExecutor;
-use gpui::{serde_json, AppContext};
 use isahc::http::StatusCode;
 use isahc::prelude::Configurable;
 use isahc::{AsyncBody, Response};
@@ -11,6 +11,7 @@ use parking_lot::{Mutex, RwLock};
 use parse_duration::parse;
 use postage::watch;
 use serde::{Deserialize, Serialize};
+use serde_json;
 use std::env;
 use std::ops::Add;
 use std::sync::Arc;

crates/client/Cargo.toml

@@ -36,6 +36,7 @@ rand.workspace = true
 schemars.workspace = true
 serde.workspace = true
 serde_derive.workspace = true
+serde_json.workspace = true
 smol.workspace = true
 sysinfo.workspace = true
 tempfile = "3"

crates/client/src/client.rs

@@ -15,8 +15,8 @@ use futures::{
     TryFutureExt as _, TryStreamExt,
 };
 use gpui::{
-    actions, serde_json, AnyModel, AnyWeakModel, AppContext, AsyncAppContext, Model,
-    SemanticVersion, Task, WeakModel,
+    actions, AnyModel, AnyWeakModel, AppContext, AsyncAppContext, Model, SemanticVersion, Task,
+    WeakModel,
 };
 use lazy_static::lazy_static;
 use parking_lot::RwLock;
@@ -25,6 +25,7 @@ use rand::prelude::*;
 use rpc::proto::{AnyTypedEnvelope, EntityMessage, EnvelopedMessage, PeerId, RequestMessage};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
+use serde_json;
 use settings::Settings;
 use std::{
     any::TypeId,

crates/client/src/telemetry.rs

@@ -1,10 +1,11 @@
 use crate::{TelemetrySettings, ZED_SECRET_CLIENT_TOKEN, ZED_SERVER_URL};
 use chrono::{DateTime, Utc};
 use futures::Future;
-use gpui::{serde_json, AppContext, AppMetadata, BackgroundExecutor, Task};
+use gpui::{AppContext, AppMetadata, BackgroundExecutor, Task};
 use lazy_static::lazy_static;
 use parking_lot::Mutex;
 use serde::Serialize;
+use serde_json;
 use settings::{Settings, SettingsStore};
 use std::{env, io::Write, mem, path::PathBuf, sync::Arc, time::Duration};
 use sysinfo::{

crates/collab_ui/Cargo.toml

@@ -61,6 +61,7 @@ schemars.workspace = true
 postage.workspace = true
 serde.workspace = true
 serde_derive.workspace = true
+serde_json.workspace = true
 time.workspace = true
 smallvec.workspace = true
 

crates/collab_ui/src/chat_panel.rs

@@ -7,9 +7,9 @@ use collections::HashMap;
 use db::kvp::KEY_VALUE_STORE;
 use editor::Editor;
 use gpui::{
-    actions, div, list, prelude::*, px, serde_json, AnyElement, AppContext, AsyncWindowContext,
-    ClickEvent, ElementId, EventEmitter, FocusableView, ListOffset, ListScrollEvent, ListState,
-    Model, Render, Subscription, Task, View, ViewContext, VisualContext, WeakView,
+    actions, div, list, prelude::*, px, AnyElement, AppContext, AsyncWindowContext, ClickEvent,
+    ElementId, EventEmitter, FocusableView, ListOffset, ListScrollEvent, ListState, Model, Render,
+    Subscription, Task, View, ViewContext, VisualContext, WeakView,
 };
 use language::LanguageRegistry;
 use menu::Confirm;

crates/collab_ui/src/collab_panel.rs

@@ -15,12 +15,12 @@ use editor::{Editor, EditorElement, EditorStyle};
 use feature_flags::{ChannelsAlpha, FeatureFlagAppExt, FeatureFlagViewExt};
 use fuzzy::{match_strings, StringMatchCandidate};
 use gpui::{
-    actions, canvas, div, fill, list, overlay, point, prelude::*, px, serde_json, AnyElement,
-    AppContext, AsyncWindowContext, Bounds, ClipboardItem, DismissEvent, Div, EventEmitter,
-    FocusHandle, FocusableView, FontStyle, FontWeight, InteractiveElement, IntoElement, ListOffset,
-    ListState, Model, MouseDownEvent, ParentElement, Pixels, Point, PromptLevel, Render,
-    RenderOnce, SharedString, Styled, Subscription, Task, TextStyle, View, ViewContext,
-    VisualContext, WeakView, WhiteSpace,
+    actions, canvas, div, fill, list, overlay, point, prelude::*, px, AnyElement, AppContext,
+    AsyncWindowContext, Bounds, ClipboardItem, DismissEvent, Div, EventEmitter, FocusHandle,
+    FocusableView, FontStyle, FontWeight, InteractiveElement, IntoElement, ListOffset, ListState,
+    Model, MouseDownEvent, ParentElement, Pixels, Point, PromptLevel, Render, RenderOnce,
+    SharedString, Styled, Subscription, Task, TextStyle, View, ViewContext, VisualContext,
+    WeakView, WhiteSpace,
 };
 use menu::{Cancel, Confirm, SelectNext, SelectPrev};
 use project::{Fs, Project};

crates/collab_ui/src/notification_panel.rs

@@ -6,11 +6,11 @@ use collections::HashMap;
 use db::kvp::KEY_VALUE_STORE;
 use futures::StreamExt;
 use gpui::{
-    actions, div, img, list, px, serde_json, AnyElement, AppContext, AsyncWindowContext,
-    CursorStyle, DismissEvent, Element, EventEmitter, FocusHandle, FocusableView,
-    InteractiveElement, IntoElement, ListAlignment, ListScrollEvent, ListState, Model,
-    ParentElement, Render, StatefulInteractiveElement, Styled, Task, View, ViewContext,
-    VisualContext, WeakView, WindowContext,
+    actions, div, img, list, px, AnyElement, AppContext, AsyncWindowContext, CursorStyle,
+    DismissEvent, Element, EventEmitter, FocusHandle, FocusableView, InteractiveElement,
+    IntoElement, ListAlignment, ListScrollEvent, ListState, Model, ParentElement, Render,
+    StatefulInteractiveElement, Styled, Task, View, ViewContext, VisualContext, WeakView,
+    WindowContext,
 };
 use notifications::{NotificationEntry, NotificationEvent, NotificationStore};
 use project::Fs;

crates/editor/src/editor_tests.rs

@@ -9,11 +9,7 @@ use crate::{
 };
 
 use futures::StreamExt;
-use gpui::{
-    div,
-    serde_json::{self, json},
-    TestAppContext, VisualTestContext, WindowBounds, WindowOptions,
-};
+use gpui::{div, TestAppContext, VisualTestContext, WindowBounds, WindowOptions};
 use indoc::indoc;
 use language::{
     language_settings::{AllLanguageSettings, AllLanguageSettingsContent, LanguageSettingsContent},
@@ -24,6 +20,7 @@ use language::{
 use parking_lot::Mutex;
 use project::project_settings::{LspSettings, ProjectSettings};
 use project::FakeFs;
+use serde_json::{self, json};
 use std::sync::atomic;
 use std::sync::atomic::AtomicUsize;
 use std::{cell::RefCell, future::Future, rc::Rc, time::Instant};

crates/editor/src/test/editor_test_context.rs

@@ -39,7 +39,7 @@ impl EditorTestContext {
         // fs.insert_file("/file", "".to_owned()).await;
         fs.insert_tree(
             "/root",
-            gpui::serde_json::json!({
+            serde_json::json!({
                 "file": "",
             }),
         )

crates/feedback/Cargo.toml

@@ -36,6 +36,7 @@ postage.workspace = true
 regex.workspace = true
 serde.workspace = true
 serde_derive.workspace = true
+serde_json.workspace = true
 smallvec.workspace = true
 smol.workspace = true
 sysinfo.workspace = true

crates/feedback/src/feedback_modal.rs

@@ -7,8 +7,8 @@ use db::kvp::KEY_VALUE_STORE;
 use editor::{Editor, EditorEvent};
 use futures::AsyncReadExt;
 use gpui::{
-    div, red, rems, serde_json, AppContext, DismissEvent, EventEmitter, FocusHandle, FocusableView,
-    Model, PromptLevel, Render, Task, View, ViewContext,
+    div, red, rems, AppContext, DismissEvent, EventEmitter, FocusHandle, FocusableView, Model,
+    PromptLevel, Render, Task, View, ViewContext,
 };
 use isahc::Request;
 use language::Buffer;

crates/gpui/src/action.rs

@@ -29,7 +29,7 @@ use std::any::{Any, TypeId};
 /// macro, which only generates the code needed to register your action before `main`.
 ///
 /// ```
-/// #[derive(gpui::serde::Deserialize, std::cmp::PartialEq, std::clone::Clone)]
+/// #[derive(gpui::private::serde::Deserialize, std::cmp::PartialEq, std::clone::Clone)]
 /// pub struct Paste {
 ///     pub content: SharedString,
 /// }
@@ -158,12 +158,12 @@ impl ActionRegistry {
 macro_rules! actions {
     ($namespace:path, [ $($name:ident),* $(,)? ]) => {
         $(
-            #[derive(::std::cmp::PartialEq, ::std::clone::Clone, ::std::default::Default, gpui::serde_derive::Deserialize)]
-            #[serde(crate = "gpui::serde")]
+            #[derive(::std::cmp::PartialEq, ::std::clone::Clone, ::std::default::Default, gpui::private::serde_derive::Deserialize)]
+            #[serde(crate = "gpui::private::serde")]
             pub struct $name;
 
             gpui::__impl_action!($namespace, $name,
-                fn build(_: gpui::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
+                fn build(_: gpui::private::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
                     Ok(Box::new(Self))
                 }
             );
@@ -179,8 +179,8 @@ macro_rules! impl_actions {
     ($namespace:path, [ $($name:ident),* $(,)? ]) => {
         $(
             gpui::__impl_action!($namespace, $name,
-                fn build(value: gpui::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
-                    Ok(std::boxed::Box::new(gpui::serde_json::from_value::<Self>(value)?))
+                fn build(value: gpui::private::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
+                    Ok(std::boxed::Box::new(gpui::private::serde_json::from_value::<Self>(value)?))
                 }
             );
 

crates/gpui/src/app.rs

@@ -43,7 +43,7 @@ use util::{
     ResultExt,
 };
 
-/// Temporary(?) wrapper around RefCell<AppContext> to help us debug any double borrows.
+/// Temporary(?) wrapper around [`RefCell<AppContext>`] to help us debug any double borrows.
 /// Strongly consider removing after stabilization.
 pub struct AppCell {
     app: RefCell<AppContext>,
@@ -964,15 +964,15 @@ impl AppContext {
 
     /// Event handlers propagate events by default. Call this method to stop dispatching to
     /// event handlers with a lower z-index (mouse) or higher in the tree (keyboard). This is
-    /// the opposite of [propagate]. It's also possible to cancel a call to [propagate] by
+    /// the opposite of [`Self::propagate`]. It's also possible to cancel a call to [`Self::propagate`] by
     /// calling this method before effects are flushed.
     pub fn stop_propagation(&mut self) {
         self.propagate_event = false;
     }
 
     /// Action handlers stop propagation by default during the bubble phase of action dispatch
     /// dispatching to action handlers higher in the element tree. This is the opposite of
-    /// [stop_propagation]. It's also possible to cancel a call to [stop_propagate] by calling
+    /// [`Self::stop_propagation`]. It's also possible to cancel a call to [`Self::stop_propagation`] by calling
     /// this method before effects are flushed.
     pub fn propagate(&mut self) {
         self.propagate_event = true;

crates/gpui/src/app/entity_map.rs

@@ -1,4 +1,4 @@
-use crate::{private::Sealed, AppContext, Context, Entity, ModelContext};
+use crate::{seal::Sealed, AppContext, Context, Entity, ModelContext};
 use anyhow::{anyhow, Result};
 use derive_more::{Deref, DerefMut};
 use parking_lot::{RwLock, RwLockUpgradableReadGuard};

crates/gpui/src/geometry.rs

@@ -1582,7 +1582,6 @@ impl From<f32> for Edges<Pixels> {
 /// Represents the corners of a box in a 2D space, such as border radius.
 ///
 /// Each field represents the size of the corner on one side of the box: `top_left`, `top_right`, `bottom_right`, and `bottom_left`.
-/// ```
 #[derive(Refineable, Clone, Default, Debug, Eq, PartialEq)]
 #[refineable(Debug)]
 #[repr(C)]
@@ -2263,14 +2262,16 @@ impl From<f64> for GlobalPixels {
     }
 }
 
-/// Represents a length in rems, a unit based on the font-size of the window, which can be assigned with [WindowContext::set_rem_size].
+/// Represents a length in rems, a unit based on the font-size of the window, which can be assigned with [`WindowContext::set_rem_size`][set_rem_size].
 ///
 /// Rems are used for defining lengths that are scalable and consistent across different UI elements.
 /// The value of `1rem` is typically equal to the font-size of the root element (often the `<html>` element in browsers),
 /// making it a flexible unit that adapts to the user's text size preferences. In this framework, `rems` serve a similar
 /// purpose, allowing for scalable and accessible design that can adjust to different display settings or user preferences.
 ///
 /// For example, if the root element's font-size is `16px`, then `1rem` equals `16px`. A length of `2rems` would then be `32px`.
+///
+/// [set_rem_size]: crate::WindowContext::set_rem_size
 #[derive(Clone, Copy, Default, Add, Sub, Mul, Div, Neg)]
 pub struct Rems(pub f32);
 

crates/gpui/src/gpui.rs

@@ -30,7 +30,16 @@ mod util;
 mod view;
 mod window;
 
-mod private {
+/// Do not touch, here be dragons for use by gpui_macros and such.
+#[doc(hidden)]
+pub mod private {
+    pub use linkme;
+    pub use serde;
+    pub use serde_derive;
+    pub use serde_json;
+}
+
+mod seal {
     /// A mechanism for restricting implementations of a trait to only those in GPUI.
     /// See: https://predr.ag/blog/definitive-guide-to-sealed-traits-in-rust/
     pub trait Sealed {}
@@ -53,16 +62,11 @@ pub use input::*;
 pub use interactive::*;
 pub use key_dispatch::*;
 pub use keymap::*;
-pub use linkme;
 pub use platform::*;
-use private::Sealed;
 pub use refineable::*;
 pub use scene::*;
-pub use serde;
-pub use serde_derive;
-pub use serde_json;
+use seal::Sealed;
 pub use shared_string::*;
-pub use smallvec;
 pub use smol::Timer;
 pub use style::*;
 pub use styled::*;

crates/gpui/src/input.rs

@@ -5,8 +5,8 @@ use std::ops::Range;
 
 /// Implement this trait to allow views to handle textual input when implementing an editor, field, etc.
 ///
-/// Once your view `V` implements this trait, you can use it to construct an [ElementInputHandler<V>].
-/// This input handler can then be assigned during paint by calling [WindowContext::handle_input].
+/// Once your view `V` implements this trait, you can use it to construct an [`ElementInputHandler<V>`].
+/// This input handler can then be assigned during paint by calling [`WindowContext::handle_input`].
 pub trait InputHandler: 'static + Sized {
     fn text_for_range(&mut self, range: Range<usize>, cx: &mut ViewContext<Self>)
         -> Option<String>;
@@ -43,8 +43,10 @@ pub struct ElementInputHandler<V> {
 }
 
 impl<V: 'static> ElementInputHandler<V> {
-    /// Used in [Element::paint] with the element's bounds and a view context for its
+    /// Used in [`Element::paint`][element_paint] with the element's bounds and a view context for its
     /// containing view.
+    ///
+    /// [element_paint]: crate::Element::paint
     pub fn new(element_bounds: Bounds<Pixels>, view: View<V>, cx: &mut WindowContext) -> Self {
         ElementInputHandler {
             view,

crates/gpui/src/platform/mac/display_linker.rs

@@ -94,7 +94,7 @@ unsafe extern "C" fn trampoline(
 
 mod sys {
     //! Derived from display-link crate under the fololwing license:
-    //! https://github.com/BrainiumLLC/display-link/blob/master/LICENSE-MIT
+    //! <https://github.com/BrainiumLLC/display-link/blob/master/LICENSE-MIT>
     //! Apple docs: [CVDisplayLink](https://developer.apple.com/documentation/corevideo/cvdisplaylinkoutputcallback?language=objc)
     #![allow(dead_code, non_upper_case_globals)]
 

crates/gpui/src/view.rs

@@ -1,5 +1,5 @@
 use crate::{
-    private::Sealed, AnyElement, AnyModel, AnyWeakModel, AppContext, AvailableSpace, BorrowWindow,
+    seal::Sealed, AnyElement, AnyModel, AnyWeakModel, AppContext, AvailableSpace, BorrowWindow,
     Bounds, Element, ElementId, Entity, EntityId, Flatten, FocusHandle, FocusableView, IntoElement,
     LayoutId, Model, Pixels, Point, Render, Size, ViewContext, VisualContext, WeakModel,
     WindowContext,