Refactor: closer port of rustc's beautify_doc_string

Per Chayim's review: split push_doc_lines into a one-line push_doc_line
and a new push_doc_lines that mirrors rustc's beautify_doc_string. The
per-line body (source-map row, trim_end, indent tracking, string push)
now lives in one place and is shared with the doc-attr / macro-expanded
fast paths.

Copies of get_vertical_trim and get_horizontal_trim are close-to-verbatim
ports of rustc's helpers, adapted only to take a (line, offset) tuple so
per-line source-map offsets stay accurate; the deviation is called out
inline. The trim application in push_doc_lines matches rustc's structure
(strip horizontal, then strip an additional leading '*' when it's block
decoration).

Preserves source-map offsets by computing each line's byte offset from
the doc start manually (no substr_range, since the workspace MSRV is 1.95)
and adding it to the caller's ast_offset when pushing each surviving line.

One test expectation moved: with the verbatim horizontal-trim application,
a doc line like ' *bar' now becomes '*bar' (rustc strips just the ' '
prefix, since '*bar' doesn't match the block-decoration triple). That
pins the block's min indent at 0, so surrounding lines keep their
post-horizontal leading whitespace. Behavior matches rustdoc.

Author: kivancgnlp

crates/hir-def/src/attrs/docs.rs

@@ -201,14 +201,8 @@ impl Docs {
 
     fn extend_with_doc_comment(&mut self, comment: ast::Comment, indent: &mut usize) {
         let Some((doc, offset)) = comment.doc_comment() else { return };
-        // Multiline block doc comments are usually decorated with a leading `*` on every line,
-        // and may be framed by lines of all `*`s. Mirror rustdoc's beautification.
-        let trim = match comment.kind().shape {
-            ast::CommentShape::Block => compute_block_doc_trim(doc),
-            ast::CommentShape::Line => None,
-        };
         let offset = comment.syntax().text_range().start() + offset;
-        self.push_doc_lines(doc, Some(offset), indent, trim.as_ref());
+        self.push_doc_lines(doc, Some(offset), indent, Some(comment.kind().shape));
     }
 
     fn extend_with_doc_attr(&mut self, value: ast::String, indent: &mut usize) {
@@ -232,48 +226,83 @@ impl Docs {
         self.push_doc_lines(doc, None, indent, None);
     }
 
-    /// `trim` is the vertical + horizontal trim for a block doc comment, as computed by
-    /// [`compute_block_doc_trim()`]. `None` means the doc is emitted verbatim (line docs, doc
-    /// attributes, macro-expanded doc strings).
+    /// Beautifies `doc` and appends the result to `self.docs`, one line at a time via
+    /// [`Docs::push_doc_line`]. Mirrors rustc's [`beautify_doc_string`] when `shape` is
+    /// `Some`, delegating to [`get_vertical_trim`] and [`get_horizontal_trim`]. When `shape`
+    /// is `None` (doc attributes and macro-expanded doc strings) the beautifier is skipped
+    /// and every line is emitted verbatim.
+    ///
+    /// Individual `///` line comments always reach us as a single-line `doc`, so the
+    /// `!doc.contains('\n')` fast path fires and the block-shape logic never runs on them.
+    ///
+    /// Unlike rustc's version, which joins the beautified lines into a new interned `Symbol`,
+    /// this port carries each line's byte offset relative to `doc`'s start so
+    /// [`Docs::push_doc_line`] can record accurate per-line source-map offsets.
+    ///
+    /// [`beautify_doc_string`]: https://github.com/rust-lang/rust/blob/16a623ad672a92409b5c04beb303583c6cf72a7e/compiler/rustc_ast/src/util/comments.rs#L37
     fn push_doc_lines(
         &mut self,
         doc: &str,
-        mut ast_offset: Option<TextSize>,
+        ast_offset: Option<TextSize>,
         indent: &mut usize,
-        trim: Option<&BlockDocTrim<'_>>,
+        shape: Option<ast::CommentShape>,
     ) {
-        for (idx, raw) in doc.split('\n').enumerate() {
-            let source_len = TextSize::of(raw);
-
-            // Vertical trim: drop lines outside `keep`, but keep advancing `ast_offset` by
-            // `source_len + "\n"` so later kept lines still map back to the right source byte.
-            let dropped = trim.is_some_and(|t| !t.keep.contains(&idx));
-            if !dropped {
-                // Horizontal trim: `*`, `* ` and `**` are decoration, but `*foo` is content.
-                let line = trim
-                    .and_then(|t| t.horizontal)
-                    .and_then(|prefix| raw.strip_prefix(prefix))
-                    .filter(|&rest| rest == "*" || rest.starts_with("* ") || rest.starts_with("**"))
-                    .map_or(raw, |rest| &rest[1..]);
-
-                self.docs_source_map.push(DocsSourceMapLine {
-                    string_offset: TextSize::of(&self.docs),
-                    ast_offset: ast_offset.map(|it| it + (source_len - TextSize::of(line))),
-                });
-
-                let line = line.trim_end();
-                if let Some(line_indent) = line.chars().position(|ch| !ch.is_whitespace()) {
-                    // Empty lines are handled because `position()` returns `None` for them.
-                    *indent = std::cmp::min(*indent, line_indent);
+        if !doc.contains('\n') {
+            self.push_doc_line(doc, ast_offset, indent);
+            return;
+        }
+
+        // Each entry is `(line, offset_from_doc_start)`. The offset stays in sync with the
+        // string as we strip its prefix, so the caller can add it to `ast_offset` for the
+        // source map. Computed manually rather than via `str::substr_range` to stay compatible
+        // with the workspace's MSRV.
+        let mut lines: Vec<(&str, TextSize)> = Vec::new();
+        let mut cursor = TextSize::new(0);
+        for line in doc.split('\n') {
+            lines.push((line, cursor));
+            cursor += TextSize::of(line) + TextSize::of("\n");
+        }
+
+        let lines = match get_vertical_trim(&lines) {
+            Some((i, j)) => &mut lines[i..j],
+            None => &mut lines[..],
+        };
+        if let Some(shape) = shape
+            && let Some(horizontal) = get_horizontal_trim(lines, shape)
+        {
+            let horizontal_len = TextSize::of(horizontal.as_str());
+            // Strip `"[ \t]*\*"` from each line where present, exactly like rustc.
+            for (line, line_offset) in lines.iter_mut() {
+                if let Some(rest) = line.strip_prefix(horizontal.as_str()) {
+                    *line = rest;
+                    *line_offset += horizontal_len;
+                    if shape == ast::CommentShape::Block
+                        && (*line == "*" || line.starts_with("* ") || line.starts_with("**"))
+                    {
+                        *line = &line[1..];
+                        *line_offset += TextSize::of("*");
+                    }
                 }
-                self.docs.push_str(line);
-                self.docs.push('\n');
             }
+        }
 
-            if let Some(offset) = ast_offset.as_mut() {
-                *offset += source_len + TextSize::of("\n");
-            }
+        for (line, line_offset) in lines.iter().copied() {
+            self.push_doc_line(line, ast_offset.map(|it| it + line_offset), indent);
+        }
+    }
+
+    /// Appends a single beautified line to `self.docs` and records its source-map row.
+    fn push_doc_line(&mut self, line: &str, ast_offset: Option<TextSize>, indent: &mut usize) {
+        self.docs_source_map
+            .push(DocsSourceMapLine { string_offset: TextSize::of(&self.docs), ast_offset });
+
+        let line = line.trim_end();
+        if let Some(line_indent) = line.chars().position(|ch| !ch.is_whitespace()) {
+            // Empty lines are handled because `position()` returns `None` for them.
+            *indent = std::cmp::min(*indent, line_indent);
         }
+        self.docs.push_str(line);
+        self.docs.push('\n');
     }
 
     fn remove_indent(&mut self, indent: usize, start_source_map_index: usize) {
@@ -380,97 +409,76 @@ impl Docs {
     }
 }
 
-/// The vertical and horizontal trim to apply to a block doc comment, mirroring rustdoc's
-/// beautification. `keep` is the half-open range of surviving *input* line indices (relative to
-/// `doc.split('\n')`); `horizontal` is the common `[ \t]*` prefix stripped from each kept line
-/// before its `*` decoration, if the block is uniformly decorated.
-#[derive(Debug)]
-struct BlockDocTrim<'a> {
-    keep: std::ops::Range<usize>,
-    horizontal: Option<&'a str>,
-}
-
-/// Computes the trim to apply to a block doc comment. Returns `None` when no trimming would take
-/// place, so the caller stays on the fast path (single-line blocks, blocks without a consistent
-/// star column, etc.).
-///
-/// Adapted from rustc's [`beautify_doc_string`], keeping the `CommentKind::Block` behavior only.
-/// The port operates on borrowed line slices instead of interning a new `Symbol`, so
-/// [`Docs::push_doc_lines`] can compute per-line source-map offsets.
-///
-/// [`beautify_doc_string`]: https://github.com/rust-lang/rust/blob/16a623ad672a92409b5c04beb303583c6cf72a7e/compiler/rustc_ast/src/util/comments.rs#L37
-fn compute_block_doc_trim(doc: &str) -> Option<BlockDocTrim<'_>> {
-    if !doc.contains('\n') {
-        // Single-line block doc comments are left alone, matching rustdoc.
-        return None;
+/// Copied verbatim from rustc's [`beautify_doc_string`] (`compiler/rustc_ast/src/util/comments.rs`
+/// @ [`16a623ad`](https://github.com/rust-lang/rust/blob/16a623ad672a92409b5c04beb303583c6cf72a7e/compiler/rustc_ast/src/util/comments.rs#L38)),
+/// except that the input is `&[(&str, TextSize)]` — the paired offset is ignored here.
+fn get_vertical_trim(lines: &[(&str, TextSize)]) -> Option<(usize, usize)> {
+    let mut i = 0;
+    let mut j = lines.len();
+    // first line of all-stars should be omitted
+    if lines.first().is_some_and(|(line, _)| !line.is_empty() && line.chars().all(|c| c == '*')) {
+        i += 1;
     }
-    let lines: Vec<&str> = doc.split('\n').collect();
 
-    // Vertical trim: drop leading/trailing all-`*` fence lines (rustc `get_vertical_trim`).
-    let mut v_start = 0usize;
-    let mut v_end = lines.len();
-    if lines[v_start].chars().all(|c| c == '*') && !lines[v_start].is_empty() {
-        v_start += 1;
-    }
-    if v_end > v_start && !lines[v_end - 1].is_empty() && lines[v_end - 1].chars().all(|c| c == '*')
-    {
-        v_end -= 1;
+    // like the first, a last line of all stars should be omitted
+    if j > i && !lines[j - 1].0.is_empty() && lines[j - 1].0.chars().all(|c| c == '*') {
+        j -= 1;
     }
 
-    // Horizontal trim: only scan lines that carry decoration. Skip the first kept line (it
-    // follows `/**` and typically contains prose) unless it already begins with `*`, and skip
-    // whitespace-only lines at the boundaries.
-    let horizontal = {
-        let kept = &lines[v_start..v_end];
-        let mut i =
-            kept.first().map(|l| if l.trim_start().starts_with('*') { 0 } else { 1 }).unwrap_or(0);
-        let mut j = kept.len();
-        while i < j && kept[i].trim().is_empty() {
-            i += 1;
-        }
-        while j > i && kept[j - 1].trim().is_empty() {
-            j -= 1;
-        }
-        let scan = &kept[i..j];
-
-        // Only whitespace + `*` is allowed in the prefix, and the `*` must sit at the same
-        // column on every scanned line. Empty scan means no decoration to strip.
-        let mut prefix_col: Option<usize> = None;
-        let mut ok = !scan.is_empty();
-        'outer: for line in scan {
-            let mut hit_star = false;
-            for (col, c) in line.chars().enumerate() {
-                if prefix_col.is_some_and(|p| col > p) || !matches!(c, '*' | ' ' | '\t') {
-                    ok = false;
-                    break 'outer;
-                }
-                if c == '*' {
-                    match prefix_col {
-                        None => prefix_col = Some(col),
-                        Some(p) if p != col => {
-                            ok = false;
-                            break 'outer;
-                        }
-                        _ => {}
-                    }
-                    hit_star = true;
-                    break;
-                }
+    if i != 0 || j != lines.len() { Some((i, j)) } else { None }
+}
+
+/// Copied verbatim from rustc's [`beautify_doc_string`] (`compiler/rustc_ast/src/util/comments.rs`
+/// @ [`16a623ad`](https://github.com/rust-lang/rust/blob/16a623ad672a92409b5c04beb303583c6cf72a7e/compiler/rustc_ast/src/util/comments.rs#L54)),
+/// except that the input is `&[(&str, TextSize)]` (the offset is ignored) and the return type is
+/// `Option<String>` for parity with the upstream signature.
+fn get_horizontal_trim(lines: &[(&str, TextSize)], kind: ast::CommentShape) -> Option<String> {
+    let mut i = usize::MAX;
+    let mut first = true;
+
+    // In case we have doc comments like `/**` or `/*!`, we want to remove stars if they are
+    // present. However, we first need to strip the empty lines so they don't get in the middle
+    // when we try to compute the "horizontal trim".
+    let lines = match kind {
+        ast::CommentShape::Block => {
+            // Whatever happens, we skip the first line.
+            let mut i = lines
+                .first()
+                .map(|(l, _)| if l.trim_start().starts_with('*') { 0 } else { 1 })
+                .unwrap_or(0);
+            let mut j = lines.len();
+
+            while i < j && lines[i].0.trim().is_empty() {
+                i += 1;
             }
-            if !hit_star {
-                // A scanned line without a `*` at the expected column means the block is not
-                // uniformly decorated.
-                ok = false;
-                break;
+            while j > i && lines[j - 1].0.trim().is_empty() {
+                j -= 1;
             }
+            &lines[i..j]
         }
-        prefix_col.filter(|_| ok).map(|p| &scan[0][..p])
+        ast::CommentShape::Line => lines,
     };
 
-    if v_start == 0 && v_end == lines.len() && horizontal.is_none() {
-        return None;
+    for (line, _) in lines {
+        for (j, c) in line.chars().enumerate() {
+            if j > i || !"* \t".contains(c) {
+                return None;
+            }
+            if c == '*' {
+                if first {
+                    i = j;
+                    first = false;
+                } else if i != j {
+                    return None;
+                }
+                break;
+            }
+        }
+        if i >= line.len() {
+            return None;
+        }
     }
-    Some(BlockDocTrim { keep: v_start..v_end, horizontal })
+    Some(lines.first()?.0[..i].to_string())
 }
 
 struct DocMacroExpander<'db> {
@@ -925,13 +933,17 @@ mod tests {
         }
 
         // The decoration is stripped, but markdown bullets and `*foo` are content.
+        // `*bar` doesn't start with `* ` / `**`, so rustc's beautifier only strips the
+        // horizontal `[ \t]*` prefix (here a single space) and leaves the leading `*` in
+        // place. That in turn pins the block's minimum indent at 0, so surrounding lines
+        // aren't re-indented.
         check(
             "/**\n * foo\n *\n *   * bullet\n *bar\n */",
             expect![[r#"
 
-                foo
+                 foo
 
-                  * bullet
+                   * bullet
                 *bar
             "#]],
         );