Marshall Bowers created
This PR updates the tenses used by the summary line of doc comments to
match the [Rust API documentation
conventions](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#summary-sentence).
Specifically:
> The summary line should be written in third person singular present
indicative form. Basically, this means write ‘Returns’ instead of
‘Return’.
I'm sure there are plenty occurrences that I missed.
Release Notes:
- N/Acrates/collab/src/db/queries/notifications.rs | 2
crates/collab/src/db/queries/users.rs | 4
crates/collab/src/rpc.rs | 16 +++---
crates/gpui/src/app.rs | 8 +-
crates/gpui/src/app/entity_map.rs | 6 +-
crates/gpui/src/app/model_context.rs | 2
crates/gpui/src/app/test_context.rs | 2
crates/gpui/src/executor.rs | 2
crates/gpui/src/view.rs | 4
crates/gpui/src/window.rs | 46 ++++++++++----------
crates/language/src/syntax_map.rs | 2
crates/plugin_runtime/src/plugin.rs | 6 +-
crates/project/src/worktree.rs | 2
crates/settings/src/settings_store.rs | 10 ++--
crates/terminal/src/terminal.rs | 2
crates/terminal/src/terminal_settings.rs | 14 +++---
crates/terminal_view/src/terminal_view.rs | 2
crates/ui/src/components/label/label.rs | 2
crates/vim/src/object.rs | 16 ++++---
19 files changed, 75 insertions(+), 73 deletions(-)
@@ -66,7 +66,7 @@ impl Database {
.await
}
- /// Create a notification. If `avoid_duplicates` is set to true, then avoid
+ /// Creates a notification. If `avoid_duplicates` is set to true, then avoid
/// creating a new notification if the given recipient already has an
/// unread notification with the given kind and entity id.
pub async fn create_notification(
@@ -153,7 +153,7 @@ impl Database {
.await
}
- /// Set "connected_once" on the user for analytics.
+ /// Sets "connected_once" on the user for analytics.
pub async fn set_user_connected_once(&self, id: UserId, connected_once: bool) -> Result<()> {
self.transaction(|tx| async move {
user::Entity::update_many()
@@ -252,7 +252,7 @@ impl Database {
.await
}
- /// Return the active flags for the user.
+ /// Returns the active flags for the user.
pub async fn get_user_flags(&self, user: UserId) -> Result<Vec<String>> {
self.transaction(|tx| async move {
#[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)]
@@ -950,7 +950,7 @@ async fn ping(_: proto::Ping, response: Response<proto::Ping>, _session: Session
Ok(())
}
-/// Create a new room for calling (outside of channels)
+/// Creates a new room for calling (outside of channels)
async fn create_room(
_request: proto::CreateRoom,
response: Response<proto::CreateRoom>,
@@ -1276,7 +1276,7 @@ async fn leave_room(
Ok(())
}
-/// Update the permissions of someone else in the room.
+/// Updates the permissions of someone else in the room.
async fn set_room_participant_role(
request: proto::SetRoomParticipantRole,
response: Response<proto::SetRoomParticipantRole>,
@@ -1460,7 +1460,7 @@ async fn decline_call(message: proto::DeclineCall, session: Session) -> Result<(
Ok(())
}
-/// Update other participants in the room with your current location.
+/// Updates other participants in the room with your current location.
async fn update_participant_location(
request: proto::UpdateParticipantLocation,
response: Response<proto::UpdateParticipantLocation>,
@@ -1673,7 +1673,7 @@ async fn leave_project(request: proto::LeaveProject, session: Session) -> Result
Ok(())
}
-/// Update other participants with changes to the project
+/// Updates other participants with changes to the project
async fn update_project(
request: proto::UpdateProject,
response: Response<proto::UpdateProject>,
@@ -1700,7 +1700,7 @@ async fn update_project(
Ok(())
}
-/// Update other participants with changes to the worktree
+/// Updates other participants with changes to the worktree
async fn update_worktree(
request: proto::UpdateWorktree,
response: Response<proto::UpdateWorktree>,
@@ -1725,7 +1725,7 @@ async fn update_worktree(
Ok(())
}
-/// Update other participants with changes to the diagnostics
+/// Updates other participants with changes to the diagnostics
async fn update_diagnostic_summary(
message: proto::UpdateDiagnosticSummary,
session: Session,
@@ -1749,7 +1749,7 @@ async fn update_diagnostic_summary(
Ok(())
}
-/// Update other participants with changes to the worktree settings
+/// Updates other participants with changes to the worktree settings
async fn update_worktree_settings(
message: proto::UpdateWorktreeSettings,
session: Session,
@@ -2293,7 +2293,7 @@ async fn remove_contact(
Ok(())
}
-/// Create a new channel.
+/// Creates a new channel.
async fn create_channel(
request: proto::CreateChannel,
response: Response<proto::CreateChannel>,
@@ -864,7 +864,7 @@ impl AppContext {
.unwrap()
}
- /// Set the value of the global of the given type.
+ /// Sets the value of the global of the given type.
pub fn set_global<G: Any>(&mut self, global: G) {
let global_type = TypeId::of::<G>();
self.push_effect(Effect::NotifyGlobalObservers { global_type });
@@ -889,7 +889,7 @@ impl AppContext {
.unwrap()
}
- /// Update the global of the given type with a closure. Unlike `global_mut`, this method provides
+ /// Updates the global of the given type with a closure. Unlike `global_mut`, this method provides
/// your closure with mutable access to the `AppContext` and the global simultaneously.
pub fn update_global<G: 'static, R>(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R {
self.update(|cx| {
@@ -1106,7 +1106,7 @@ impl AppContext {
.contains_key(&action.as_any().type_id())
}
- /// Set the menu bar for this application. This will replace any existing menu bar.
+ /// Sets the menu bar for this application. This will replace any existing menu bar.
pub fn set_menus(&mut self, menus: Vec<Menu>) {
self.platform.set_menus(menus, &self.keymap.lock());
}
@@ -1190,7 +1190,7 @@ impl Context for AppContext {
})
}
- /// Update the entity referenced by the given model. The function is passed a mutable reference to the
+ /// Updates the entity referenced by the given model. The function is passed a mutable reference to the
/// entity along with a `ModelContext` for the entity.
fn update_model<T: 'static, R>(
&mut self,
@@ -104,7 +104,7 @@ impl EntityMap {
}
}
- /// Return an entity after moving it to the stack.
+ /// Returns an entity after moving it to the stack.
pub fn end_lease<T>(&mut self, mut lease: Lease<T>) {
self.entities
.insert(lease.model.entity_id, lease.entity.take().unwrap());
@@ -391,7 +391,7 @@ impl<T: 'static> Model<T> {
cx.read_model(self, f)
}
- /// Update the entity referenced by this model with the given function.
+ /// Updates the entity referenced by this model with the given function.
///
/// The update function receives a context appropriate for its environment.
/// When updating in an `AppContext`, it receives a `ModelContext`.
@@ -571,7 +571,7 @@ impl<T: 'static> WeakModel<T> {
Model::upgrade_from(self)
}
- /// Update the entity referenced by this model with the given function if
+ /// Updates the entity referenced by this model with the given function if
/// the referenced entity still exists. Returns an error if the entity has
/// been released.
pub fn update<C, R>(
@@ -189,7 +189,7 @@ impl<'a, T: 'static> ModelContext<'a, T> {
}
}
- /// Update the given global
+ /// Updates the given global
pub fn update_global<G, R>(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R
where
G: 'static,
@@ -578,7 +578,7 @@ impl<'a> VisualTestContext {
self.cx.update_window(self.window, |_, cx| f(cx)).unwrap()
}
- /// Create a new VisualTestContext. You would typically shadow the passed in
+ /// Creates a new VisualTestContext. You would typically shadow the passed in
/// TestAppContext with this, as this is typically more useful.
/// `let cx = VisualTestContext::from_window(window, cx);`
pub fn from_window(window: AnyWindowHandle, cx: &TestAppContext) -> Self {
@@ -46,7 +46,7 @@ pub enum Task<T> {
}
impl<T> Task<T> {
- /// Create a new task that will resolve with the value
+ /// Creates a new task that will resolve with the value
pub fn ready(val: T) -> Self {
Task::Ready(Some(val))
}
@@ -64,7 +64,7 @@ impl<V: 'static> View<V> {
Entity::downgrade(self)
}
- /// Update the view's state with the given function, which is passed a mutable reference and a context.
+ /// Updates the view's state with the given function, which is passed a mutable reference and a context.
pub fn update<C, R>(
&self,
cx: &mut C,
@@ -156,7 +156,7 @@ impl<V: 'static> WeakView<V> {
Entity::upgrade_from(self)
}
- /// Update this view's state if it hasn't been released.
+ /// Updates this view's state if it hasn't been released.
/// Returns an error if this view has been released.
pub fn update<C, R>(
&self,
@@ -721,7 +721,7 @@ impl<'a> WindowContext<'a> {
subscription
}
- /// Create an `AsyncWindowContext`, which has a static lifetime and can be held across
+ /// Creates an [`AsyncWindowContext`], which has a static lifetime and can be held across
/// await points in async code.
pub fn to_async(&self) -> AsyncWindowContext {
AsyncWindowContext::new(self.app.to_async(), self.window.handle)
@@ -794,7 +794,7 @@ impl<'a> WindowContext<'a> {
.spawn(|app| f(AsyncWindowContext::new(app, self.window.handle)))
}
- /// Update the global of the given type. The given closure is given simultaneous mutable
+ /// Updates the global of the given type. The given closure is given simultaneous mutable
/// access both to the global and the context.
pub fn update_global<G, R>(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R
where
@@ -913,7 +913,7 @@ impl<'a> WindowContext<'a> {
self.window.platform_window.zoom();
}
- /// Update the window's title at the platform level.
+ /// Updates the window's title at the platform level.
pub fn set_window_title(&mut self, title: &str) {
self.window.platform_window.set_title(title);
}
@@ -1063,14 +1063,14 @@ impl<'a> WindowContext<'a> {
self.window.modifiers
}
- /// Update the cursor style at the platform level.
+ /// Updates the cursor style at the platform level.
pub fn set_cursor_style(&mut self, style: CursorStyle) {
let view_id = self.parent_view_id();
self.window.next_frame.cursor_styles.insert(view_id, style);
self.window.next_frame.requested_cursor_style = Some(style);
}
- /// Set a tooltip to be rendered for the upcoming frame
+ /// Sets a tooltip to be rendered for the upcoming frame
pub fn set_tooltip(&mut self, tooltip: AnyTooltip) {
let view_id = self.parent_view_id();
self.window.next_frame.tooltip_request = Some(TooltipRequest { view_id, tooltip });
@@ -2080,8 +2080,8 @@ impl<'a> WindowContext<'a> {
})
}
- /// Update or initialize state for an element with the given id that lives across multiple
- /// frames. If an element with this id existed in the rendered frame, its state will be passed
+ /// Updates or initializes state for an element with the given id that lives across multiple
+ /// frames. If an element with this ID existed in the rendered frame, its state will be passed
/// to the given closure. The state returned by the closure will be stored so it can be referenced
/// when drawing the next frame.
pub(crate) fn with_element_state<S, R>(
@@ -2182,7 +2182,7 @@ impl<'a> WindowContext<'a> {
.expect("a view should always be on the stack while drawing")
}
- /// Set an input handler, such as [`ElementInputHandler`][element_input_handler], which interfaces with the
+ /// Sets 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. This handler will be active for the upcoming frame until the following frame is
/// rendered.
@@ -2322,7 +2322,7 @@ impl VisualContext for WindowContext<'_> {
view
}
- /// Update the given view. Prefer calling `View::update` instead, which calls this method.
+ /// Updates the given view. Prefer calling [`View::update`] instead, which calls this method.
fn update_view<T: 'static, R>(
&mut self,
view: &View<T>,
@@ -2491,7 +2491,7 @@ pub trait BorrowWindow: BorrowMut<Window> + BorrowMut<AppContext> {
result
}
- /// Update the global element offset relative to the current offset. This is used to implement
+ /// Updates the global element offset relative to the current offset. This is used to implement
/// scrolling.
fn with_element_offset<R>(
&mut self,
@@ -2506,7 +2506,7 @@ pub trait BorrowWindow: BorrowMut<Window> + BorrowMut<AppContext> {
self.with_absolute_element_offset(abs_offset, f)
}
- /// Update the global element offset based on the given offset. This is used to implement
+ /// Updates the global element offset based on the given offset. This is used to implement
/// drag handles and other manual painting of elements.
fn with_absolute_element_offset<R>(
&mut self,
@@ -2629,7 +2629,7 @@ impl<'a, V: 'static> ViewContext<'a, V> {
&mut self.window_cx
}
- /// Set a given callback to be run on the next frame.
+ /// Sets a given callback to be run on the next frame.
pub fn on_next_frame(&mut self, f: impl FnOnce(&mut V, &mut ViewContext<V>) + 'static)
where
V: 'static,
@@ -2957,7 +2957,7 @@ impl<'a, V: 'static> ViewContext<'a, V> {
self.window_cx.spawn(|cx| f(view, cx))
}
- /// Update the global state of the given type.
+ /// Updates the global state of the given type.
pub fn update_global<G, R>(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R
where
G: 'static,
@@ -3189,7 +3189,7 @@ pub struct WindowHandle<V> {
}
impl<V: 'static + Render> WindowHandle<V> {
- /// Create a new handle from a window ID.
+ /// Creates a new handle from a window ID.
/// This does not check if the root type of the window is `V`.
pub fn new(id: WindowId) -> Self {
WindowHandle {
@@ -3215,7 +3215,7 @@ impl<V: 'static + Render> WindowHandle<V> {
}))
}
- /// Update the root view of this window.
+ /// Updates the root view of this window.
///
/// This will fail if the window has been closed or if the root view's type does not match
pub fn update<C, R>(
@@ -3337,7 +3337,7 @@ impl AnyWindowHandle {
}
}
- /// Update the state of the root view of this window.
+ /// Updates the state of the root view of this window.
///
/// This will fail if the window has been closed.
pub fn update<C, R>(
@@ -3477,7 +3477,7 @@ pub struct PaintQuad {
}
impl PaintQuad {
- /// Set the corner radii of the quad.
+ /// Sets the corner radii of the quad.
pub fn corner_radii(self, corner_radii: impl Into<Corners<Pixels>>) -> Self {
PaintQuad {
corner_radii: corner_radii.into(),
@@ -3485,7 +3485,7 @@ impl PaintQuad {
}
}
- /// Set the border widths of the quad.
+ /// Sets the border widths of the quad.
pub fn border_widths(self, border_widths: impl Into<Edges<Pixels>>) -> Self {
PaintQuad {
border_widths: border_widths.into(),
@@ -3493,7 +3493,7 @@ impl PaintQuad {
}
}
- /// Set the border color of the quad.
+ /// Sets the border color of the quad.
pub fn border_color(self, border_color: impl Into<Hsla>) -> Self {
PaintQuad {
border_color: border_color.into(),
@@ -3501,7 +3501,7 @@ impl PaintQuad {
}
}
- /// Set the background color of the quad.
+ /// Sets the background color of the quad.
pub fn background(self, background: impl Into<Hsla>) -> Self {
PaintQuad {
background: background.into(),
@@ -3510,7 +3510,7 @@ impl PaintQuad {
}
}
-/// Create a quad with the given parameters.
+/// Creates a quad with the given parameters.
pub fn quad(
bounds: Bounds<Pixels>,
corner_radii: impl Into<Corners<Pixels>>,
@@ -3527,7 +3527,7 @@ pub fn quad(
}
}
-/// Create a filled quad with the given bounds and background color.
+/// Creates a filled quad with the given bounds and background color.
pub fn fill(bounds: impl Into<Bounds<Pixels>>, background: impl Into<Hsla>) -> PaintQuad {
PaintQuad {
bounds: bounds.into(),
@@ -3538,7 +3538,7 @@ pub fn fill(bounds: impl Into<Bounds<Pixels>>, background: impl Into<Hsla>) -> P
}
}
-/// Create a rectangle outline with the given bounds, border color, and a 1px border width
+/// Creates a rectangle outline with the given bounds, border color, and a 1px border width
pub fn outline(bounds: impl Into<Bounds<Pixels>>, border_color: impl Into<Hsla>) -> PaintQuad {
PaintQuad {
bounds: bounds.into(),
@@ -1296,7 +1296,7 @@ fn get_injections(
}
}
-/// Update the given list of included `ranges`, removing any ranges that intersect
+/// Updates the given list of included `ranges`, removing any ranges that intersect
/// `removed_ranges`, and inserting the given `new_ranges`.
///
/// Returns a new vector of ranges, and the range of the vector that was changed,
@@ -69,7 +69,7 @@ impl Default for Metering {
}
/// This struct is used to build a new [`Plugin`], using the builder pattern.
-/// Create a new default plugin with `PluginBuilder::new_with_default_ctx`,
+/// Creates a new default plugin with `PluginBuilder::new_with_default_ctx`,
/// and add host-side exported functions using `host_function` and `host_function_async`.
/// Finalize the plugin by calling [`init`].
pub struct PluginBuilder {
@@ -90,7 +90,7 @@ fn create_default_engine() -> Result<Engine, Error> {
}
impl PluginBuilder {
- /// Create a new [`PluginBuilder`] with the given WASI context.
+ /// Creates a new [`PluginBuilder`] with the given WASI context.
/// Using the default context is a safe bet, see [`new_with_default_context`].
/// This plugin will yield after a configurable amount of fuel is consumed.
pub fn new(wasi_ctx: WasiCtx, metering: Metering) -> Result<Self, Error> {
@@ -105,7 +105,7 @@ impl PluginBuilder {
})
}
- /// Create a new `PluginBuilder` with the default `WasiCtx` (see [`default_ctx`]).
+ /// Creates a new `PluginBuilder` with the default `WasiCtx` (see [`default_ctx`]).
/// This plugin will yield after a configurable amount of fuel is consumed.
pub fn new_default() -> Result<Self, Error> {
let default_ctx = WasiCtxBuilder::new()
@@ -1866,7 +1866,7 @@ impl Snapshot {
})
}
- /// Update the `git_status` of the given entries such that files'
+ /// Updates the `git_status` of the given entries such that files'
/// statuses bubble up to their ancestor directories.
pub fn propagate_git_statuses(&self, result: &mut [Entry]) {
let mut cursor = self
@@ -246,7 +246,7 @@ impl SettingsStore {
this
}
- /// Update the value of a setting in the user's global configuration.
+ /// Updates the value of a setting in the user's global configuration.
///
/// This is only for tests. Normally, settings are only loaded from
/// JSON files.
@@ -261,7 +261,7 @@ impl SettingsStore {
self.set_user_settings(&new_text, cx).unwrap();
}
- /// Update the value of a setting in a JSON file, returning the new text
+ /// Updates the value of a setting in a JSON file, returning the new text
/// for that JSON file.
pub fn new_text_for_update<T: Settings>(
&self,
@@ -276,7 +276,7 @@ impl SettingsStore {
new_text
}
- /// Update the value of a setting in a JSON file, returning a list
+ /// Updates the value of a setting in a JSON file, returning a list
/// of edits to apply to the JSON file.
pub fn edits_for_update<T: Settings>(
&self,
@@ -344,7 +344,7 @@ impl SettingsStore {
DEFAULT_JSON_TAB_SIZE
}
- /// Set the default settings via a JSON string.
+ /// Sets the default settings via a JSON string.
///
/// The string should contain a JSON object with a default value for every setting.
pub fn set_default_settings(
@@ -362,7 +362,7 @@ impl SettingsStore {
}
}
- /// Set the user settings via a JSON string.
+ /// Sets the user settings via a JSON string.
pub fn set_user_settings(
&mut self,
user_settings_content: &str,
@@ -599,7 +599,7 @@ impl Terminal {
}
}
- /// Update the cached process info, returns whether the Zed-relevant info has changed
+ /// Updates the cached process info, returns whether the Zed-relevant info has changed
fn update_process_info(&mut self) -> bool {
let mut pid = unsafe { libc::tcgetpgrp(self.shell_fd as i32) };
if pid < 0 {
@@ -90,17 +90,17 @@ pub struct TerminalSettingsContent {
///
/// Default: current_project_directory
pub working_directory: Option<WorkingDirectory>,
- /// Set the terminal's font size.
+ /// Sets the terminal's font size.
///
/// If this option is not included,
/// the terminal will default to matching the buffer's font size.
pub font_size: Option<f32>,
- /// Set the terminal's font family.
+ /// Sets the terminal's font family.
///
/// If this option is not included,
/// the terminal will default to matching the buffer's font family.
pub font_family: Option<String>,
- /// Set the terminal's line height.
+ /// Sets the terminal's line height.
///
/// Default: comfortable
pub line_height: Option<TerminalLineHeight>,
@@ -110,18 +110,18 @@ pub struct TerminalSettingsContent {
///
/// Default: {}
pub env: Option<HashMap<String, String>>,
- /// Set the cursor blinking behavior in the terminal.
+ /// Sets the cursor blinking behavior in the terminal.
///
/// Default: terminal_controlled
pub blinking: Option<TerminalBlink>,
- /// Set whether Alternate Scroll mode (code: ?1007) is active by default.
+ /// Sets whether Alternate Scroll mode (code: ?1007) is active by default.
/// Alternate Scroll mode converts mouse scroll events into up / down key
/// presses when in the alternate screen (e.g. when running applications
/// like vim or less). The terminal can still set and unset this mode.
///
/// Default: off
pub alternate_scroll: Option<AlternateScroll>,
- /// Set whether the option key behaves as the meta key.
+ /// Sets whether the option key behaves as the meta key.
///
/// Default: false
pub option_as_meta: Option<bool>,
@@ -139,7 +139,7 @@ pub struct TerminalSettingsContent {
///
/// Default: 320
pub default_height: Option<f32>,
- /// Activate the python virtual environment, if one is found, in the
+ /// Activates the python virtual environment, if one is found, in the
/// terminal's working directory (as resolved by the working_directory
/// setting). Set this to "off" to disable this behavior.
///
@@ -832,7 +832,7 @@ impl SearchableItem for TerminalView {
self.terminal().update(cx, |term, _| term.matches = matches)
}
- /// Return the selection content to pre-load into this search
+ /// Returns the selection content to pre-load into this search
fn query_suggestion(&mut self, cx: &mut ViewContext<Self>) -> String {
self.terminal()
.read(cx)
@@ -37,7 +37,7 @@ pub struct Label {
}
impl Label {
- /// Create a new [`Label`] with the given text.
+ /// Creates a new [`Label`] with the given text.
///
/// # Examples
///
@@ -195,9 +195,10 @@ impl Object {
}
}
-/// Return a range that surrounds the word relative_to is in
-/// If relative_to is at the start of a word, return the word.
-/// If relative_to is between words, return the space between
+/// Returns a range that surrounds the word `relative_to` is in.
+///
+/// If `relative_to` is at the start of a word, return the word.
+/// If `relative_to` is between words, return the space between.
fn in_word(
map: &DisplaySnapshot,
relative_to: DisplayPoint,
@@ -225,11 +226,12 @@ fn in_word(
Some(start..end)
}
-/// Return a range that surrounds the word and following whitespace
+/// Returns a range that surrounds the word and following whitespace
/// relative_to is in.
-/// If relative_to is at the start of a word, return the word and following whitespace.
-/// If relative_to is between words, return the whitespace back and the following word
-
+///
+/// If `relative_to` is at the start of a word, return the word and following whitespace.
+/// If `relative_to` is between words, return the whitespace back and the following word.
+///
/// if in word
/// delete that word
/// if there is whitespace following the word, delete that as well