improve document and comment

crates/workspace/src/views/repo_detail/browser.rs

@@ -39,12 +39,9 @@ pub(super) enum FileContent {
 
 /// A markdown document loaded into a persistent [`TextViewState`].
 ///
-/// The state is owned by the view rather than created per render (as the
-/// stateless `text::markdown` helper does), so it survives branch switches
-/// in the content pane. GPUI's keyed element state is dropped as soon as the
-/// element is absent for a single frame, which would otherwise re-parse the
-/// whole document on the main thread every time the pane switches between
-/// the README, a file preview, and the loading spinner.
+/// The state is owned by the view rather than created per render: GPUI
+/// drops keyed element state after one absent frame, which would re-parse
+/// the whole document on every pane switch (README / file / spinner).
 pub(super) struct MarkdownView {
     /// Source path; `None` means the repository README.
     pub(super) path: Option<SharedString>,
@@ -53,11 +50,7 @@ pub(super) struct MarkdownView {
 
 /// A code file loaded into a persistent [`InputState`], rendered as a
 /// disabled (read-only) code editor with syntax highlighting, line numbers
-/// and search.
-///
-/// Same persistence rationale as [`MarkdownView`]: the state lives as long
-/// as this view, so re-viewing the same file does not re-parse it, and
-/// parsing happens on a background task inside the editor.
+/// and search. Persistent for the same reason as [`MarkdownView`].
 pub(super) struct CodeView {
     /// Source path, relative to the worktree root.
     pub(super) path: SharedString,
@@ -230,9 +223,7 @@ impl RepoDetailView {
     /// Load `text` into the persistent markdown TextView state.
     ///
     /// The state is created empty and fed via `push_str`, which parses on a
-    /// background task: switching files never blocks the main thread, and
-    /// the state lives as long as this view, so re-viewing the same document
-    /// does not re-parse it.
+    /// background task, so switching files never blocks the main thread.
     pub(super) fn set_markdown(
         &mut self,
         path: Option<SharedString>,
@@ -269,10 +260,8 @@ impl RepoDetailView {
     /// Load `text` into the persistent code editor state for `path`.
     ///
     /// The state is created in code editor mode so the Input renders it as
-    /// a syntax-highlighted, read-only editor. Like [`set_markdown`], the
-    /// state lives as long as this view, so re-viewing the same file does
-    /// not re-parse it; the tree-sitter parse runs on a background task
-    /// inside the editor instead of blocking the main thread.
+    /// a syntax-highlighted, read-only editor; the tree-sitter parse runs
+    /// on a background task like [`set_markdown`]'s.
     pub(super) fn set_code(
         &mut self,
         path: SharedString,

crates/workspace/src/views/repo_detail/helpers.rs

@@ -276,11 +276,8 @@ pub(super) fn status_badge(status: RepoStatus, cx: &App) -> AnyElement {
 /// A split dropdown button built on `gpui_base::Popover`: an action element
 /// with a separate caret trigger that opens a [`PopupMenu`].
 ///
-/// The action and the caret are ordinary elements supplied by the caller, so
-/// the look — icons, borders, hover states, sizes — stays fully in the
-/// application. The component only owns the popover wiring: opening on caret
-/// click, Escape/outside dismissal, focus movement into the menu, and the
-/// menu entity's lifecycle.
+/// The action and the caret are caller-supplied elements, so the look stays
+/// in the application; this component only owns the popover wiring.
 #[derive(IntoElement)]
 pub(super) struct BaseDropdownButton {
     id: ElementId,
@@ -493,11 +490,10 @@ impl ShareTargets {
     }
 }
 
-/// One row of the share menu: a small title on top of the compact label,
-/// with a copy button that flips to a check while the value is on the
-/// clipboard. Clicking the row text copies and dismisses the menu; the copy
-/// button stops propagation, so the menu stays open for further copies.
-/// Both copy `copy`, never the truncated label.
+/// One row of the share menu: a small title above the compact label, with
+/// a copy button that flips to a check while the value is on the clipboard.
+/// Clicking the row copies and dismisses the menu; the copy button stops
+/// propagation so the menu stays open. Both copy `copy`, never the label.
 pub(super) fn share_menu_row(
     id: &'static str,
     title: &'static str,

crates/workspace/src/views/repo_detail/issues.rs

@@ -26,10 +26,8 @@ use super::helpers::{placeholder, status_badge};
 use super::issue_detail::IssueDetailView;
 use crate::image_cache::{MAX_IMAGES, image_cache};
 
-/// Height of one issue row in the virtual list: 8px vertical padding
-/// (`py_2`) on top and bottom, a 32px title line (`h_8`) and a 24px meta
-/// line (`h_6`), plus the 1px bottom border; the row totals 73px. The
-/// status chip (`size_7`, 28px) is shorter than the content.
+/// Height of one issue row in the virtual list: `py_2` padding, a 32px
+/// title line (`h_8`), a 24px meta line (`h_6`) and the 1px bottom border.
 const ISSUE_ROW_HEIGHT: f32 = 73.;
 
 /// Status filter of the issues list, chosen via the header's filter buttons.
@@ -39,8 +37,8 @@ enum IssueFilter {
     All,
     /// Issues whose resolved status is [`RepoStatus::Open`].
     Open,
-    /// Issues whose resolved status is
-    /// [`RepoStatus::Closed`] or [`RepoStatus::Applied`] (both are "done" states).
+    /// Issues whose resolved status is [`RepoStatus::Closed`] or
+    /// [`RepoStatus::Applied`] (both are "done" states).
     Closed,
 }
 

crates/workspace/src/views/repo_detail/mod.rs

@@ -308,9 +308,7 @@ impl RepoDetailView {
     /// (not yet published) repository is opened straight from disk. An
     /// announced repository's local clone (if any) is loaded first without
     /// touching the network, so an unreachable server can't block the
-    /// panel; a background fetch then refreshes the refs and commit list
-    /// (a fetch never changes the checked-out files, so the tree and
-    /// previews are left alone).
+    /// panel; a background fetch then refreshes the refs and commit list.
     fn load_repo(&mut self, window: &mut Window, cx: &mut Context<Self>) {
         self.loading = true;
         self.error = None;
@@ -505,9 +503,7 @@ impl RepoDetailView {
     }
 
     /// Clone the repository into a folder chosen by the user (outside the
-    /// cache), then open the new clone in the system file manager. Like
-    /// ngit's clone, this resolves the announcement's `clone` URLs and
-    /// clones from the first working git server.
+    /// cache), then open the new clone in the system file manager.
     fn clone_to_folder(&mut self, window: &mut Window, cx: &mut Context<Self>) {
         if self.cloning {
             return;
@@ -722,11 +718,8 @@ impl RepoDetailView {
 
     /// Walk history once for every queued path on a background task, and
     /// cache the latest commit touching each of them in [`Self::commits`]
-    /// (for the file header in the content column).
-    ///
-    /// Batching shares one walk (and its object decodes) across all paths
-    /// queued while the previous walk was in flight, instead of walking the
-    /// full history per file.
+    /// (for the file header in the content column). Batching shares one
+    /// walk across all paths queued while the previous walk was in flight.
     fn load_commits(&mut self, cx: &mut Context<Self>) {
         if self.pending_commits.is_empty() || self.loading_commits {
             return;
@@ -1029,8 +1022,7 @@ impl RepoDetailView {
 
     /// Trigger body for the branch/tag selectors: the kind icon, the
     /// selection (or placeholder) and the caret. `Combobox` replaces its
-    /// default trigger entirely, which is the only way to show an icon
-    /// inside the trigger label.
+    /// default trigger entirely, the only way to show an icon inside it.
     fn render_ref_trigger(
         ctx: &ComboboxTriggerContext<SearchableVec<SharedString>>,
         icon: CustomIconName,
@@ -1923,9 +1915,7 @@ impl Render for RepoDetailView {
 }
 
 /// Read the worktree state of `repo` (no network): entries, README, refs
-/// and HEAD commit. The tree is built off the main thread; the seeds are
-/// plain owned strings and convert to `TreeItem`s (which hold `Rc` state)
-/// on the main thread.
+/// and HEAD commit.
 fn load_repo_data(repo: &Repository) -> Result<RepoData, Error> {
     let entries = signed_git::worktree_entries(repo)?;
     let tree = build_tree_items(&entries);

crates/workspace/src/views/repo_detail/pull_request_detail.rs

@@ -146,9 +146,8 @@ impl PullRequestDetailView {
     /// and commit list on a background task and populate the tree.
     ///
     /// The changes come from the PR's patch set (NIP-34 `e`-linked patch
-    /// events) when present; otherwise they live in the git repository
-    /// (`c`, `clone` and `merge-base` tags, per NIP-34), so the clone is
-    /// fetched and the `merge-base..tip` range is diffed.
+    /// events) when present; otherwise from the git repository (`c`,
+    /// `clone` and `merge-base` tags), diffing the `merge-base..tip` range.
     fn load(&mut self, window: &mut Window, cx: &mut Context<Self>) {
         self.loading = true;
         self.error = None;

crates/workspace/src/views/repo_detail/pull_requests.rs

@@ -26,11 +26,8 @@ use super::helpers::{placeholder, status_badge};
 use super::pull_request_detail::PullRequestDetailView;
 use crate::image_cache::{MAX_IMAGES, image_cache};
 
-/// Height of one pull request row in the virtual list: same layout as an
-/// issue row (8px vertical padding (`py_2`) on top and bottom, a 32px title
-/// line (`h_8`) and a 24px meta line (`h_6`), plus the 1px bottom border),
-/// so the row totals 73px. The status badge (`size_7`, 28px) is shorter
-/// than the content.
+/// Height of one pull request row in the virtual list; same layout as an
+/// issue row.
 const PR_ROW_HEIGHT: f32 = 73.;
 
 /// Status filter of the pull request list, chosen via the header's filter
@@ -79,9 +76,8 @@ pub struct PullRequestsView {
     /// pull request count); rebuilt on change.
     pr_len: usize,
     /// Indices into the store's `pull_requests` matching [`Self::filter`]
-    /// (root PR events only; updates are revisions of the root and are not
-    /// listed separately), rebuilt every render; the virtual list renders
-    /// this slice.
+    /// (root PR events only; updates are revisions of the root), rebuilt
+    /// every render; the virtual list renders this slice.
     visible_prs: Vec<usize>,
     /// Virtual list state of the pull requests list.
     scroll_handle: VirtualListScrollHandle,

crates/workspace/src/views/repo_list.rs

@@ -97,9 +97,7 @@ pub struct RepoListView {
     /// Number of rows [`Self::item_sizes`] was built for (the filtered repo count).
     repo_len: usize,
     /// Indices into the store's `announcements` matching [`Self::filter`],
-    /// in display order; rebuilt when the store changes, the filter is
-    /// switched, or the search text changes. The virtual list renders this
-    /// slice.
+    /// in display order; the virtual list renders this slice.
     visible: Vec<usize>,
     /// Search box filtering repositories by name.
     search: Entity<InputState>,
@@ -153,10 +151,7 @@ impl RepoListView {
     }
 
     /// Rebuild [`Self::visible`] and [`Self::item_sizes`] from the current
-    /// store contents, [`Self::filter`] and the search query. Called when
-    /// the view is created, when the store changes, when the filter is
-    /// switched, and on every search keystroke, so the list is ready before
-    /// the next render.
+    /// store contents, [`Self::filter`] and the search query.
     fn rebuild_rows(&mut self, cx: &mut Context<Self>) {
         let filter = self.filter;
         let query = self.search.read(cx).value();

crates/workspace/src/views/sidebar/mod.rs

@@ -417,9 +417,8 @@ impl SidebarPanel {
         )
     }
 
-    /// Sign-in placeholder shown while logged out: the banner artwork fills the
-    /// panel behind a scrim that ends in a solid black band, keeping the CTA
-    /// buttons readable on a clean dark surface in both themes.
+    /// Sign-in placeholder shown while logged out: banner artwork behind a
+    /// scrim so the CTA buttons stay readable in both themes.
     fn render_sign_in(&self, window: &mut Window, cx: &mut Context<Self>) -> Div {
         v_flex()
             .size_full()