gpui: Further docs refinement & moved some reexports into 'private' module (#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/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,7 +964,7 @@ 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;
@@ -972,7 +972,7 @@ impl AppContext {
 
     /// 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,7 +2262,7 @@ 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),
@@ -2271,6 +2270,8 @@ impl From<f64> for GlobalPixels {
 /// 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,

crates/gpui/src/window.rs

@@ -1826,9 +1826,11 @@ impl<'a> WindowContext<'a> {
         result
     }
 
-    /// Set an input handler, such as [ElementInputHandler], which interfaces with the
+    /// Set an input handler, such as [`ElementInputHandler`][element_input_handler], which interfaces with the
     /// platform to receive textual input with proper integration with concerns such
     /// as IME interactions.
+    ///
+    /// [element_input_handler]: crate::ElementInputHandler
     pub fn handle_input(
         &mut self,
         focus_handle: &FocusHandle,
@@ -2500,8 +2502,7 @@ impl<'a, V: 'static> ViewContext<'a, V> {
     }
 
     /// Register a listener to be called when the given focus handle receives focus.
-    /// Unlike [on_focus_changed], returns a subscription and persists until the subscription
-    /// is dropped.
+    /// Returns a subscription and persists until the subscription is dropped.
     pub fn on_focus(
         &mut self,
         handle: &FocusHandle,
@@ -2527,8 +2528,7 @@ impl<'a, V: 'static> ViewContext<'a, V> {
     }
 
     /// Register a listener to be called when the given focus handle or one of its descendants receives focus.
-    /// Unlike [on_focus_changed], returns a subscription and persists until the subscription
-    /// is dropped.
+    /// Returns a subscription and persists until the subscription is dropped.
     pub fn on_focus_in(
         &mut self,
         handle: &FocusHandle,
@@ -2554,8 +2554,7 @@ impl<'a, V: 'static> ViewContext<'a, V> {
     }
 
     /// Register a listener to be called when the given focus handle loses focus.
-    /// Unlike [on_focus_changed], returns a subscription and persists until the subscription
-    /// is dropped.
+    /// Returns a subscription and persists until the subscription is dropped.
     pub fn on_blur(
         &mut self,
         handle: &FocusHandle,
@@ -2581,8 +2580,7 @@ impl<'a, V: 'static> ViewContext<'a, V> {
     }
 
     /// Register a listener to be called when the window loses focus.
-    /// Unlike [on_focus_changed], returns a subscription and persists until the subscription
-    /// is dropped.
+    /// Returns a subscription and persists until the subscription is dropped.
     pub fn on_blur_window(
         &mut self,
         mut listener: impl FnMut(&mut V, &mut ViewContext<V>) + 'static,
@@ -2597,8 +2595,7 @@ impl<'a, V: 'static> ViewContext<'a, V> {
     }
 
     /// Register a listener to be called when the given focus handle or one of its descendants loses focus.
-    /// Unlike [on_focus_changed], returns a subscription and persists until the subscription
-    /// is dropped.
+    /// Returns a subscription and persists until the subscription is dropped.
     pub fn on_focus_out(
         &mut self,
         handle: &FocusHandle,