Skip to content
This repository was archived by the owner on May 28, 2025. It is now read-only.

Commit 712de2b

Browse files
petrochenkovpetrochenkov
committed
rustc_expand: Don not beautify doc comments before passing them to macros
Beautify all doc strings in rustdoc instead, including those in `#[doc]` attributes
1 parent 000c070 commit 712de2b

File tree

6 files changed

+37
-54
lines changed

6 files changed

+37
-54
lines changed

‎src/librustc_ast/util/comments.rs‎

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
use crate::ast::AttrStyle;
2-
use crate::token::CommentKind;
32
use rustc_span::source_map::SourceMap;
43
use rustc_span::{BytePos, CharPos, FileName, Pos, Symbol};
54

@@ -64,7 +63,9 @@ pub fn block_doc_comment_style(block_comment: &str, terminated: bool) -> Option<
6463
}
6564
}
6665

67-
pub fn strip_doc_comment_decoration(data: Symbol, comment_kind: CommentKind) -> String {
66+
/// Makes a doc string more presentable to users.
67+
/// Used by rustdoc and perhaps other tools, but not by rustc.
68+
pub fn beautify_doc_string(data: Symbol) -> String {
6869
/// remove whitespace-only lines from the start/end of lines
6970
fn vertical_trim(lines: Vec<String>) -> Vec<String> {
7071
let mut i = 0;
@@ -126,18 +127,14 @@ pub fn strip_doc_comment_decoration(data: Symbol, comment_kind: CommentKind) ->
126127
}
127128
}
128129

129-
match comment_kind {
130-
CommentKind::Line => {
131-
let data = data.as_str();
132-
let prefix_len = if data.starts_with('!') { 1 } else { 0 };
133-
data[prefix_len..].to_string()
134-
}
135-
CommentKind::Block => {
136-
let lines = data.as_str().lines().map(|s| s.to_string()).collect::<Vec<String>>();
137-
let lines = vertical_trim(lines);
138-
let lines = horizontal_trim(lines);
139-
lines.join("\n")
140-
}
130+
let data = data.as_str();
131+
if data.contains('\n') {
132+
let lines = data.lines().map(|s| s.to_string()).collect::<Vec<String>>();
133+
let lines = vertical_trim(lines);
134+
let lines = horizontal_trim(lines);
135+
lines.join("\n")
136+
} else {
137+
data.to_string()
141138
}
142139
}
143140

‎src/librustc_ast/util/comments/tests.rs‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ fn line_doc_comments() {
1212
fn test_block_doc_comment_1() {
1313
with_default_session_globals(|| {
1414
let comment = "\n * Test \n ** Test\n * Test\n";
15-
let stripped = strip_doc_comment_decoration(Symbol::intern(comment), CommentKind::Block);
15+
let stripped = beautify_doc_string(Symbol::intern(comment));
1616
assert_eq!(stripped, " Test \n* Test\n Test");
1717
})
1818
}
@@ -21,7 +21,7 @@ fn test_block_doc_comment_1() {
2121
fn test_block_doc_comment_2() {
2222
with_default_session_globals(|| {
2323
let comment = "\n * Test\n * Test\n";
24-
let stripped = strip_doc_comment_decoration(Symbol::intern(comment), CommentKind::Block);
24+
let stripped = beautify_doc_string(Symbol::intern(comment));
2525
assert_eq!(stripped, " Test\n Test");
2626
})
2727
}
@@ -30,21 +30,21 @@ fn test_block_doc_comment_2() {
3030
fn test_block_doc_comment_3() {
3131
with_default_session_globals(|| {
3232
let comment = "\n let a: *i32;\n *a = 5;\n";
33-
let stripped = strip_doc_comment_decoration(Symbol::intern(comment), CommentKind::Block);
33+
let stripped = beautify_doc_string(Symbol::intern(comment));
3434
assert_eq!(stripped, " let a: *i32;\n *a = 5;");
3535
})
3636
}
3737

3838
#[test]
3939
fn test_line_doc_comment() {
4040
with_default_session_globals(|| {
41-
let stripped = strip_doc_comment_decoration(Symbol::intern(" test"), CommentKind::Line);
41+
let stripped = beautify_doc_string(Symbol::intern(" test"));
4242
assert_eq!(stripped, " test");
43-
let stripped = strip_doc_comment_decoration(Symbol::intern("! test"), CommentKind::Line);
44-
assert_eq!(stripped, " test");
45-
let stripped = strip_doc_comment_decoration(Symbol::intern("test"), CommentKind::Line);
46-
assert_eq!(stripped, "test");
47-
let stripped = strip_doc_comment_decoration(Symbol::intern("!test"), CommentKind::Line);
43+
let stripped = beautify_doc_string(Symbol::intern("! test"));
44+
assert_eq!(stripped, "! test");
45+
let stripped = beautify_doc_string(Symbol::intern("test"));
4846
assert_eq!(stripped, "test");
47+
let stripped = beautify_doc_string(Symbol::intern("!test"));
48+
assert_eq!(stripped, "!test");
4949
})
5050
}

‎src/librustc_expand/proc_macro_server.rs‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@ use crate::base::ExtCtxt;
33
use rustc_ast::ast;
44
use rustc_ast::token;
55
use rustc_ast::tokenstream::{self, DelimSpan, IsJoint::*, TokenStream, TreeAndJoint};
6-
use rustc_ast::util::comments;
76
use rustc_ast_pretty::pprust;
87
use rustc_data_structures::sync::Lrc;
98
use rustc_errors::Diagnostic;
@@ -148,10 +147,9 @@ impl FromInternal<(TreeAndJoint, &'_ ParseSess, &'_ mut Vec<Self>)>
148147
tt!(Punct::new('\'', true))
149148
}
150149
Literal(lit) => tt!(Literal { lit }),
151-
DocComment(comment_kind, attr_style, data) => {
152-
let stripped = comments::strip_doc_comment_decoration(data, comment_kind);
150+
DocComment(_, attr_style, data) => {
153151
let mut escaped = String::new();
154-
for ch in stripped.chars() {
152+
for ch in data.as_str().chars() {
155153
escaped.extend(ch.escape_debug());
156154
}
157155
let stream = vec![

‎src/librustc_parse/parser/mod.rs‎

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,6 @@ use rustc_ast::ast::{
2222
use rustc_ast::ptr::P;
2323
use rustc_ast::token::{self, DelimToken, Token, TokenKind};
2424
use rustc_ast::tokenstream::{self, DelimSpan, TokenStream, TokenTree, TreeAndJoint};
25-
use rustc_ast::util::comments::strip_doc_comment_decoration;
2625
use rustc_ast_pretty::pprust;
2726
use rustc_errors::{struct_span_err, Applicability, DiagnosticBuilder, FatalError, PResult};
2827
use rustc_session::parse::ParseSess;
@@ -209,20 +208,18 @@ impl TokenCursor {
209208
}
210209

211210
fn next_desugared(&mut self) -> Token {
212-
let (data, comment_kind, attr_style, sp) = match self.next() {
213-
Token { kind: token::DocComment(comment_kind, attr_style, data), span } => {
214-
(data, comment_kind, attr_style, span)
211+
let (data, attr_style, sp) = match self.next() {
212+
Token { kind: token::DocComment(_, attr_style, data), span } => {
213+
(data, attr_style, span)
215214
}
216215
tok => return tok,
217216
};
218217

219-
let stripped = strip_doc_comment_decoration(data, comment_kind);
220-
221218
// Searches for the occurrences of `"#*` and returns the minimum number of `#`s
222219
// required to wrap the text.
223220
let mut num_of_hashes = 0;
224221
let mut count = 0;
225-
for ch in stripped.chars() {
222+
for ch in data.as_str().chars() {
226223
count = match ch {
227224
'"' => 1,
228225
'#' if count > 0 => count + 1,
@@ -238,10 +235,7 @@ impl TokenCursor {
238235
[
239236
TokenTree::token(token::Ident(sym::doc, false), sp),
240237
TokenTree::token(token::Eq, sp),
241-
TokenTree::token(
242-
TokenKind::lit(token::StrRaw(num_of_hashes), Symbol::intern(&stripped), None),
243-
sp,
244-
),
238+
TokenTree::token(TokenKind::lit(token::StrRaw(num_of_hashes), data, None), sp),
245239
]
246240
.iter()
247241
.cloned()

‎src/librustc_save_analysis/lib.rs‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ mod span_utils;
1010
mod sig;
1111

1212
use rustc_ast::ast::{self};
13-
use rustc_ast::util::comments::strip_doc_comment_decoration;
13+
use rustc_ast::util::comments::beautify_doc_string;
1414
use rustc_ast_pretty::pprust::attribute_to_string;
1515
use rustc_hir as hir;
1616
use rustc_hir::def::{DefKind as HirDefKind, Res};
@@ -822,11 +822,8 @@ impl<'tcx> SaveContext<'tcx> {
822822

823823
for attr in attrs {
824824
if let Some(val) = attr.doc_str() {
825-
if let ast::AttrKind::DocComment(comment_kind, _) = attr.kind {
826-
result.push_str(&strip_doc_comment_decoration(val, comment_kind));
827-
} else {
828-
result.push_str(&val.as_str());
829-
}
825+
// FIXME: Should save-analysis beautify doc strings itself or leave it to users?
826+
result.push_str(&beautify_doc_string(val));
830827
result.push('\n');
831828
} else if attr.check_name(sym::doc) {
832829
if let Some(meta_list) = attr.meta_item_list() {

‎src/librustdoc/clean/types.rs‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ use std::{slice, vec};
1010

1111
use rustc_ast::ast::{self, AttrStyle};
1212
use rustc_ast::attr;
13-
use rustc_ast::util::comments::strip_doc_comment_decoration;
13+
use rustc_ast::util::comments::beautify_doc_string;
1414
use rustc_data_structures::fx::{FxHashMap, FxHashSet};
1515
use rustc_hir as hir;
1616
use rustc_hir::def::Res;
@@ -506,15 +506,12 @@ impl Attributes {
506506
.iter()
507507
.filter_map(|attr| {
508508
if let Some(value) = attr.doc_str() {
509-
let (value, mk_fragment): (_, fn(_, _, _) -> _) =
510-
if let ast::AttrKind::DocComment(comment_kind, _) = attr.kind {
511-
(
512-
strip_doc_comment_decoration(value, comment_kind),
513-
DocFragment::SugaredDoc,
514-
)
515-
} else {
516-
(value.to_string(), DocFragment::RawDoc)
517-
};
509+
let value = beautify_doc_string(value);
510+
let mk_fragment: fn(_, _, _) -> _ = if attr.is_doc_comment() {
511+
DocFragment::SugaredDoc
512+
} else {
513+
DocFragment::RawDoc
514+
};
518515

519516
let line = doc_line;
520517
doc_line += value.lines().count();

0 commit comments

Comments
 (0)