From 74dadd68d251e2b9cd93158bad2d1c4c726ac311 Mon Sep 17 00:00:00 2001 From: Marshall Bowers Date: Tue, 9 Jan 2024 14:48:48 -0500 Subject: [PATCH] Clean up references in doc comments (#3983) This PR cleans up a number of references in doc comments so that `rustdoc` will link and display them correctly. Release Notes: - N/A --- crates/gpui/src/app.rs | 10 ++--- crates/gpui/src/element.rs | 10 ++--- crates/gpui/src/executor.rs | 8 ++-- crates/gpui/src/input.rs | 2 +- crates/gpui/src/platform/mac/display.rs | 4 +- crates/gpui/src/subscription.rs | 6 +-- crates/gpui/src/window.rs | 50 ++++++++++++------------- crates/rope/src/rope.rs | 6 +-- crates/text/src/anchor.rs | 2 +- 9 files changed, 50 insertions(+), 48 deletions(-) diff --git a/crates/gpui/src/app.rs b/crates/gpui/src/app.rs index f84ae809d3..108ad28d24 100644 --- a/crates/gpui/src/app.rs +++ b/crates/gpui/src/app.rs @@ -163,17 +163,17 @@ impl App { self.0.borrow().app_metadata.clone() } - /// Returns a handle to the [BackgroundExecutor] associated with this app, which can be used to spawn futures in the background. + /// Returns a handle to the [`BackgroundExecutor`] associated with this app, which can be used to spawn futures in the background. pub fn background_executor(&self) -> BackgroundExecutor { self.0.borrow().background_executor.clone() } - /// Returns a handle to the [ForegroundExecutor] associated with this app, which can be used to spawn futures in the foreground. + /// Returns a handle to the [`ForegroundExecutor`] associated with this app, which can be used to spawn futures in the foreground. pub fn foreground_executor(&self) -> ForegroundExecutor { self.0.borrow().foreground_executor.clone() } - /// Returns a reference to the [TextSystem] associated with this app. + /// Returns a reference to the [`TextSystem`] associated with this app. pub fn text_system(&self) -> Arc { self.0.borrow().text_system.clone() } @@ -299,7 +299,7 @@ impl AppContext { app } - /// Quit the application gracefully. Handlers registered with `ModelContext::on_app_quit` + /// Quit the application gracefully. Handlers registered with [`ModelContext::on_app_quit`] /// will be given 100ms to complete before exiting. pub fn shutdown(&mut self) { let mut futures = Vec::new(); @@ -580,7 +580,7 @@ impl AppContext { self.pending_effects.push_back(effect); } - /// Called at the end of AppContext::update to complete any side effects + /// Called at the end of [`AppContext::update`] to complete any side effects /// such as notifying observers, emitting events, etc. Effects can themselves /// cause effects, so we continue looping until all effects are processed. fn flush_effects(&mut self) { diff --git a/crates/gpui/src/element.rs b/crates/gpui/src/element.rs index 987b91b791..179c2cb1e2 100644 --- a/crates/gpui/src/element.rs +++ b/crates/gpui/src/element.rs @@ -31,14 +31,14 @@ pub trait IntoElement: Sized { /// The specific type of element into which the implementing type is converted. type Element: Element; - /// The [ElementId] of self once converted into an [Element]. + /// The [`ElementId`] of self once converted into an [`Element`]. /// If present, the resulting element's state will be carried across frames. fn element_id(&self) -> Option; - /// Convert self into a type that implements [Element]. + /// Convert self into a type that implements [`Element`]. fn into_element(self) -> Self::Element; - /// Convert self into a dynamically-typed [AnyElement]. + /// Convert self into a dynamically-typed [`AnyElement`]. fn into_any_element(self) -> AnyElement { self.into_element().into_any() } @@ -115,7 +115,7 @@ pub trait Render: 'static + Sized { fn render(&mut self, cx: &mut ViewContext) -> impl IntoElement; } -/// You can derive [IntoElement] on any type that implements this trait. +/// You can derive [`IntoElement`] on any type that implements this trait. /// It is used to allow views to be expressed in terms of abstract data. pub trait RenderOnce: 'static { fn render(self, cx: &mut WindowContext) -> impl IntoElement; @@ -224,7 +224,7 @@ enum ElementDrawPhase { }, } -/// A wrapper around an implementer of [Element] that allows it to be drawn in a window. +/// A wrapper around an implementer of [`Element`] that allows it to be drawn in a window. impl DrawableElement { fn new(element: E) -> Self { DrawableElement { diff --git a/crates/gpui/src/executor.rs b/crates/gpui/src/executor.rs index 4be1ffbf0f..fc60cb1ec6 100644 --- a/crates/gpui/src/executor.rs +++ b/crates/gpui/src/executor.rs @@ -33,8 +33,10 @@ pub struct ForegroundExecutor { } /// Task is a primitive that allows work to happen in the background. -/// It implements Future so you can `.await` on it. -/// If you drop a task it will be cancelled immediately. Calling `.detach()` allows +/// +/// It implements [`Future`] so you can `.await` on it. +/// +/// If you drop a task it will be cancelled immediately. Calling [`Task::detach`] allows /// the task to continue running in the background, but with no way to return a value. #[must_use] #[derive(Debug)] @@ -387,7 +389,7 @@ impl ForegroundExecutor { } } -/// Scope manages a set of tasks that are enqueued and waited on together. See `BackgroundExecutor#scoped` +/// Scope manages a set of tasks that are enqueued and waited on together. See [`BackgroundExecutor::scoped`]. pub struct Scope<'a> { executor: BackgroundExecutor, futures: Vec + Send + 'static>>>, diff --git a/crates/gpui/src/input.rs b/crates/gpui/src/input.rs index da240a77a8..7290b48abd 100644 --- a/crates/gpui/src/input.rs +++ b/crates/gpui/src/input.rs @@ -34,7 +34,7 @@ pub trait InputHandler: 'static + Sized { ) -> Option>; } -/// The canonical implementation of `PlatformInputHandler`. Call `WindowContext::handle_input` +/// The canonical implementation of [`PlatformInputHandler`]. Call [`WindowContext::handle_input`] /// with an instance during your element's paint. pub struct ElementInputHandler { view: View, diff --git a/crates/gpui/src/platform/mac/display.rs b/crates/gpui/src/platform/mac/display.rs index 123cbf8159..25e0921fee 100644 --- a/crates/gpui/src/platform/mac/display.rs +++ b/crates/gpui/src/platform/mac/display.rs @@ -14,12 +14,12 @@ pub struct MacDisplay(pub(crate) CGDirectDisplayID); unsafe impl Send for MacDisplay {} impl MacDisplay { - /// Get the screen with the given [DisplayId]. + /// Get the screen with the given [`DisplayId`]. pub fn find_by_id(id: DisplayId) -> Option { Self::all().find(|screen| screen.id() == id) } - /// Get the screen with the given persistent [Uuid]. + /// Get the screen with the given persistent [`Uuid`]. pub fn find_by_uuid(uuid: Uuid) -> Option { Self::all().find(|screen| screen.uuid().ok() == Some(uuid)) } diff --git a/crates/gpui/src/subscription.rs b/crates/gpui/src/subscription.rs index b56c9a1ccd..887283d094 100644 --- a/crates/gpui/src/subscription.rs +++ b/crates/gpui/src/subscription.rs @@ -37,10 +37,10 @@ where }))) } - /// Inserts a new `[Subscription]` for the given `emitter_key`. By default, subscriptions + /// Inserts a new [`Subscription`] for the given `emitter_key`. By default, subscriptions /// are inert, meaning that they won't be listed when calling `[SubscriberSet::remove]` or `[SubscriberSet::retain]`. - /// This method returns a tuple of a `[Subscription]` and an `impl FnOnce`, and you can use the latter - /// to activate the `[Subscription]`. + /// This method returns a tuple of a [`Subscription`] and an `impl FnOnce`, and you can use the latter + /// to activate the [`Subscription`]. #[must_use] pub fn insert( &self, diff --git a/crates/gpui/src/window.rs b/crates/gpui/src/window.rs index 9b657a3f71..ec4713639e 100644 --- a/crates/gpui/src/window.rs +++ b/crates/gpui/src/window.rs @@ -248,7 +248,7 @@ pub trait ManagedView: FocusableView + EventEmitter {} impl> ManagedView for M {} -/// Emitted by implementers of [ManagedView] to indicate the view should be dismissed, such as when a view is presented as a modal. +/// Emitted by implementers of [`ManagedView`] to indicate the view should be dismissed, such as when a view is presented as a modal. pub struct DismissEvent; // Holds the state for a specific window. @@ -464,8 +464,8 @@ impl ContentMask { } /// Provides access to application state in the context of a single window. Derefs -/// to an `AppContext`, so you can also pass a `WindowContext` to any method that takes -/// an `AppContext` and call any `AppContext` methods. +/// to an [`AppContext`], so you can also pass a [`WindowContext`] to any method that takes +/// an [`AppContext`] and call any [`AppContext`] methods. pub struct WindowContext<'a> { pub(crate) app: &'a mut AppContext, pub(crate) window: &'a mut Window, @@ -493,20 +493,20 @@ impl<'a> WindowContext<'a> { self.window.removed = true; } - /// Obtain a new `FocusHandle`, which allows you to track and manipulate the keyboard focus + /// Obtain a new [`FocusHandle`], which allows you to track and manipulate the keyboard focus /// for elements rendered within this window. pub fn focus_handle(&mut self) -> FocusHandle { FocusHandle::new(&self.window.focus_handles) } - /// Obtain the currently focused `FocusHandle`. If no elements are focused, returns `None`. + /// Obtain the currently focused [`FocusHandle`]. If no elements are focused, returns `None`. pub fn focused(&self) -> Option { self.window .focus .and_then(|id| FocusHandle::for_id(id, &self.window.focus_handles)) } - /// Move focus to the element associated with the given `FocusHandle`. + /// Move focus to the element associated with the given [`FocusHandle`]. pub fn focus(&mut self, handle: &FocusHandle) { if !self.window.focus_enabled || self.window.focus == Some(handle.id) { return; @@ -605,8 +605,8 @@ impl<'a> WindowContext<'a> { } /// Subscribe to events emitted by a model or view. - /// The entity to which you're subscribing must implement the [EventEmitter] trait. - /// The callback will be invoked a handle to the emitting entity (either a [View] or [Model]), the event, and a window context for the current window. + /// The entity to which you're subscribing must implement the [`EventEmitter`] trait. + /// The callback will be invoked a handle to the emitting entity (either a [`View`] or [`Model`]), the event, and a window context for the current window. pub fn subscribe( &mut self, entity: &E, @@ -2061,7 +2061,7 @@ impl<'a> BorrowMut for WindowContext<'a> { } } -/// This trait contains functionality that is shared across [ViewContext] and [WindowContext] +/// This trait contains functionality that is shared across [`ViewContext`] and [`WindowContext`] pub trait BorrowWindow: BorrowMut + BorrowMut { #[doc(hidden)] fn app_mut(&mut self) -> &mut AppContext { @@ -2328,10 +2328,10 @@ impl BorrowMut for WindowContext<'_> { impl BorrowWindow for T where T: BorrowMut + BorrowMut {} -/// Provides access to application state that is specialized for a particular [View]. +/// Provides access to application state that is specialized for a particular [`View`]. /// Allows you to interact with focus, emit events, etc. -/// ViewContext also derefs to [WindowContext], giving you access to all of its methods as well. -/// When you call [View::::update], you're passed a `&mut V` and an `&mut ViewContext`. +/// ViewContext also derefs to [`WindowContext`], giving you access to all of its methods as well. +/// When you call [`View::update`], you're passed a `&mut V` and an `&mut ViewContext`. pub struct ViewContext<'a, V> { window_cx: WindowContext<'a>, view: &'a View, @@ -2407,7 +2407,7 @@ impl<'a, V: 'static> ViewContext<'a, V> { }); } - /// Observe another model or view for changes to it's state, as tracked by the [AppContext::notify] + /// Observe another model or view for changes to its state, as tracked by [`ModelContext::notify`]. pub fn observe( &mut self, entity: &E, @@ -2442,8 +2442,8 @@ impl<'a, V: 'static> ViewContext<'a, V> { } /// Subscribe to events emitted by another model or view. - /// The entity to which you're subscribing must implement the [EventEmitter] trait. - /// The callback will be invoked with a reference to the current view, a handle to the emitting entity (either a [View] or [Model]), the event, and a view context for the current view. + /// The entity to which you're subscribing must implement the [`EventEmitter`] trait. + /// The callback will be invoked with a reference to the current view, a handle to the emitting entity (either a [`View`] or [`Model`]), the event, and a view context for the current view. pub fn subscribe( &mut self, entity: &E, @@ -2687,8 +2687,8 @@ impl<'a, V: 'static> ViewContext<'a, V> { } /// Schedule a future to be run asynchronously. - /// The given callback is invoked with a [WeakView] to avoid leaking the view for a long-running process. - /// It's also given an `AsyncWindowContext`, which can be used to access the state of the view across await points. + /// The given callback is invoked with a [`WeakView`] to avoid leaking the view for a long-running process. + /// It's also given an [`AsyncWindowContext`], which can be used to access the state of the view across await points. /// The returned future will be polled on the main thread. pub fn spawn( &mut self, @@ -2789,7 +2789,7 @@ impl<'a, V: 'static> ViewContext<'a, V> { }); } - /// Move focus to the current view, assuming it implements [FocusableView]. + /// Move focus to the current view, assuming it implements [`FocusableView`]. pub fn focus_self(&mut self) where V: FocusableView, @@ -3119,21 +3119,21 @@ impl AnyWindowHandle { // } // } -/// An identifier for an [Element]. +/// An identifier for an [`Element`](crate::Element). /// /// Can be constructed with a string, a number, or both, as well /// as other internal representations. #[derive(Clone, Debug, Eq, PartialEq, Hash)] pub enum ElementId { - /// The id of a View element + /// The ID of a View element View(EntityId), - /// An integer id + /// An integer ID. Integer(usize), - /// A string based id + /// A string based ID. Name(SharedString), - /// An id that's equated with a focus handle + /// An ID that's equated with a focus handle. FocusHandle(FocusId), - /// A combination of a name and an integer + /// A combination of a name and an integer. NamedInteger(SharedString, usize), } @@ -3204,7 +3204,7 @@ impl From<(&'static str, u64)> for ElementId { } /// A rectangle to be rendered in the window at the given position and size. -/// Passed as an argument [WindowContext::paint_quad]. +/// Passed as an argument [`WindowContext::paint_quad`]. #[derive(Clone)] pub struct PaintQuad { bounds: Bounds, diff --git a/crates/rope/src/rope.rs b/crates/rope/src/rope.rs index adfcd19a6c..05873818c7 100644 --- a/crates/rope/src/rope.rs +++ b/crates/rope/src/rope.rs @@ -25,10 +25,10 @@ const CHUNK_BASE: usize = 6; #[cfg(not(test))] const CHUNK_BASE: usize = 16; -/// Type alias to [HashMatrix], an implementation of a homomorphic hash function. Two [Rope] instances +/// Type alias to [`HashMatrix`], an implementation of a homomorphic hash function. Two [`Rope`] instances /// containing the same text will produce the same fingerprint. This hash function is special in that -/// it allows us to hash individual chunks and aggregate them up the [Rope]'s tree, with the resulting -/// hash being equivalent to hashing all the text contained in the [Rope] at once. +/// it allows us to hash individual chunks and aggregate them up the [`Rope`]'s tree, with the resulting +/// hash being equivalent to hashing all the text contained in the [`Rope`] at once. pub type RopeFingerprint = HashMatrix; #[derive(Clone, Default)] diff --git a/crates/text/src/anchor.rs b/crates/text/src/anchor.rs index 084be0e336..a65e3753d4 100644 --- a/crates/text/src/anchor.rs +++ b/crates/text/src/anchor.rs @@ -90,7 +90,7 @@ impl Anchor { content.summary_for_anchor(self) } - /// Returns true when the [Anchor] is located inside a visible fragment. + /// Returns true when the [`Anchor`] is located inside a visible fragment. pub fn is_valid(&self, buffer: &BufferSnapshot) -> bool { if *self == Anchor::MIN || *self == Anchor::MAX { true