1use std::mem;
2use std::ops::Range;
3
4use itertools::Itertools;
5use pulldown_cmark::{
6 BrokenLink, BrokenLinkCallback, CowStr, Event, LinkType, Options, Parser, Tag,
7};
8use rustc_ast as ast;
9use rustc_ast::attr::AttributeExt;
10use rustc_ast::util::comments::beautify_doc_string;
11use rustc_data_structures::fx::FxIndexMap;
12use rustc_data_structures::unord::UnordSet;
13use rustc_middle::ty::TyCtxt;
14use rustc_span::def_id::DefId;
15use rustc_span::source_map::SourceMap;
16use rustc_span::{DUMMY_SP, InnerSpan, Span, Symbol, sym};
17use thin_vec::ThinVec;
18use tracing::{debug, trace};
19
20#[cfg(test)]
21mod tests;
22
23#[derive(Clone, Copy, PartialEq, Eq, Debug)]
24pub enum DocFragmentKind {
25 SugaredDoc,
27 RawDoc,
29}
30
31#[derive(Clone, PartialEq, Eq, Debug)]
40pub struct DocFragment {
41 pub span: Span,
42 pub item_id: Option<DefId>,
49 pub doc: Symbol,
50 pub kind: DocFragmentKind,
51 pub indent: usize,
52}
53
54#[derive(Clone, Copy, Debug)]
55pub enum MalformedGenerics {
56 UnbalancedAngleBrackets,
60 MissingType,
66 HasFullyQualifiedSyntax,
73 InvalidPathSeparator,
85 TooManyAngleBrackets,
89 EmptyAngleBrackets,
93}
94
95pub fn unindent_doc_fragments(docs: &mut [DocFragment]) {
109 let add = if docs.windows(2).any(|arr| arr[0].kind != arr[1].kind)
122 && docs.iter().any(|d| d.kind == DocFragmentKind::SugaredDoc)
123 {
124 1
127 } else {
128 0
129 };
130
131 let Some(min_indent) = docs
141 .iter()
142 .map(|fragment| {
143 fragment
144 .doc
145 .as_str()
146 .lines()
147 .filter(|line| line.chars().any(|c| !c.is_whitespace()))
148 .map(|line| {
149 let whitespace = line.chars().take_while(|c| *c == ' ' || *c == '\t').count();
152 whitespace
153 + (if fragment.kind == DocFragmentKind::SugaredDoc { 0 } else { add })
154 })
155 .min()
156 .unwrap_or(usize::MAX)
157 })
158 .min()
159 else {
160 return;
161 };
162
163 for fragment in docs {
164 if fragment.doc == sym::empty {
165 continue;
166 }
167
168 let indent = if fragment.kind != DocFragmentKind::SugaredDoc && min_indent > 0 {
169 min_indent - add
170 } else {
171 min_indent
172 };
173
174 fragment.indent = indent;
175 }
176}
177
178pub fn add_doc_fragment(out: &mut String, frag: &DocFragment) {
184 if frag.doc == sym::empty {
185 out.push('\n');
186 return;
187 }
188 let s = frag.doc.as_str();
189 let mut iter = s.lines();
190
191 while let Some(line) = iter.next() {
192 if line.chars().any(|c| !c.is_whitespace()) {
193 assert!(line.len() >= frag.indent);
194 out.push_str(&line[frag.indent..]);
195 } else {
196 out.push_str(line);
197 }
198 out.push('\n');
199 }
200}
201
202pub fn attrs_to_doc_fragments<'a, A: AttributeExt + Clone + 'a>(
203 attrs: impl Iterator<Item = (&'a A, Option<DefId>)>,
204 doc_only: bool,
205) -> (Vec<DocFragment>, ThinVec<A>) {
206 let mut doc_fragments = Vec::new();
207 let mut other_attrs = ThinVec::<A>::new();
208 for (attr, item_id) in attrs {
209 if let Some((doc_str, comment_kind)) = attr.doc_str_and_comment_kind() {
210 let doc = beautify_doc_string(doc_str, comment_kind);
211 let (span, kind) = if attr.is_doc_comment() {
212 (attr.span(), DocFragmentKind::SugaredDoc)
213 } else {
214 (
215 attr.value_span()
216 .map(|i| i.with_ctxt(attr.span().ctxt()))
217 .unwrap_or(attr.span()),
218 DocFragmentKind::RawDoc,
219 )
220 };
221 let fragment = DocFragment { span, doc, kind, item_id, indent: 0 };
222 doc_fragments.push(fragment);
223 } else if !doc_only {
224 other_attrs.push(attr.clone());
225 }
226 }
227
228 unindent_doc_fragments(&mut doc_fragments);
229
230 (doc_fragments, other_attrs)
231}
232
233pub fn prepare_to_doc_link_resolution(
239 doc_fragments: &[DocFragment],
240) -> FxIndexMap<Option<DefId>, String> {
241 let mut res = FxIndexMap::default();
242 for fragment in doc_fragments {
243 let out_str = res.entry(fragment.item_id).or_default();
244 add_doc_fragment(out_str, fragment);
245 }
246 res
247}
248
249pub fn main_body_opts() -> Options {
251 Options::ENABLE_TABLES
252 | Options::ENABLE_FOOTNOTES
253 | Options::ENABLE_STRIKETHROUGH
254 | Options::ENABLE_TASKLISTS
255 | Options::ENABLE_SMART_PUNCTUATION
256}
257
258fn strip_generics_from_path_segment(segment: Vec<char>) -> Result<String, MalformedGenerics> {
259 let mut stripped_segment = String::new();
260 let mut param_depth = 0;
261
262 let mut latest_generics_chunk = String::new();
263
264 for c in segment {
265 if c == '<' {
266 param_depth += 1;
267 latest_generics_chunk.clear();
268 } else if c == '>' {
269 param_depth -= 1;
270 if latest_generics_chunk.contains(" as ") {
271 return Err(MalformedGenerics::HasFullyQualifiedSyntax);
274 }
275 } else if param_depth == 0 {
276 stripped_segment.push(c);
277 } else {
278 latest_generics_chunk.push(c);
279 }
280 }
281
282 if param_depth == 0 {
283 Ok(stripped_segment)
284 } else {
285 Err(MalformedGenerics::UnbalancedAngleBrackets)
287 }
288}
289
290pub fn strip_generics_from_path(path_str: &str) -> Result<Box<str>, MalformedGenerics> {
291 if !path_str.contains(['<', '>']) {
292 return Ok(path_str.into());
293 }
294 let mut stripped_segments = vec![];
295 let mut path = path_str.chars().peekable();
296 let mut segment = Vec::new();
297
298 while let Some(chr) = path.next() {
299 match chr {
300 ':' => {
301 if path.next_if_eq(&':').is_some() {
302 let stripped_segment =
303 strip_generics_from_path_segment(mem::take(&mut segment))?;
304 if !stripped_segment.is_empty() {
305 stripped_segments.push(stripped_segment);
306 }
307 } else {
308 return Err(MalformedGenerics::InvalidPathSeparator);
309 }
310 }
311 '<' => {
312 segment.push(chr);
313
314 match path.next() {
315 Some('<') => {
316 return Err(MalformedGenerics::TooManyAngleBrackets);
317 }
318 Some('>') => {
319 return Err(MalformedGenerics::EmptyAngleBrackets);
320 }
321 Some(chr) => {
322 segment.push(chr);
323
324 while let Some(chr) = path.next_if(|c| *c != '>') {
325 segment.push(chr);
326 }
327 }
328 None => break,
329 }
330 }
331 _ => segment.push(chr),
332 }
333 trace!("raw segment: {:?}", segment);
334 }
335
336 if !segment.is_empty() {
337 let stripped_segment = strip_generics_from_path_segment(segment)?;
338 if !stripped_segment.is_empty() {
339 stripped_segments.push(stripped_segment);
340 }
341 }
342
343 debug!("path_str: {path_str:?}\nstripped segments: {stripped_segments:?}");
344
345 let stripped_path = stripped_segments.join("::");
346
347 if !stripped_path.is_empty() {
348 Ok(stripped_path.into())
349 } else {
350 Err(MalformedGenerics::MissingType)
351 }
352}
353
354pub fn inner_docs(attrs: &[impl AttributeExt]) -> bool {
359 attrs.iter().find(|a| a.doc_str().is_some()).is_none_or(|a| a.style() == ast::AttrStyle::Inner)
360}
361
362pub fn has_primitive_or_keyword_docs(attrs: &[impl AttributeExt]) -> bool {
364 for attr in attrs {
365 if attr.has_name(sym::rustc_doc_primitive) {
366 return true;
367 } else if attr.has_name(sym::doc)
368 && let Some(items) = attr.meta_item_list()
369 {
370 for item in items {
371 if item.has_name(sym::keyword) {
372 return true;
373 }
374 }
375 }
376 }
377 false
378}
379
380fn preprocess_link(link: &str) -> Box<str> {
384 let link = link.replace('`', "");
385 let link = link.split('#').next().unwrap();
386 let link = link.trim();
387 let link = link.rsplit('@').next().unwrap();
388 let link = link.strip_suffix("()").unwrap_or(link);
389 let link = link.strip_suffix("{}").unwrap_or(link);
390 let link = link.strip_suffix("[]").unwrap_or(link);
391 let link = if link != "!" { link.strip_suffix('!').unwrap_or(link) } else { link };
392 let link = link.trim();
393 strip_generics_from_path(link).unwrap_or_else(|_| link.into())
394}
395
396pub fn may_be_doc_link(link_type: LinkType) -> bool {
399 match link_type {
400 LinkType::Inline
401 | LinkType::Reference
402 | LinkType::ReferenceUnknown
403 | LinkType::Collapsed
404 | LinkType::CollapsedUnknown
405 | LinkType::Shortcut
406 | LinkType::ShortcutUnknown => true,
407 LinkType::Autolink | LinkType::Email => false,
408 }
409}
410
411pub(crate) fn attrs_to_preprocessed_links<A: AttributeExt + Clone>(attrs: &[A]) -> Vec<Box<str>> {
414 let (doc_fragments, _) = attrs_to_doc_fragments(attrs.iter().map(|attr| (attr, None)), true);
415 let doc = prepare_to_doc_link_resolution(&doc_fragments).into_values().next().unwrap();
416
417 parse_links(&doc)
418}
419
420fn parse_links<'md>(doc: &'md str) -> Vec<Box<str>> {
423 let mut broken_link_callback = |link: BrokenLink<'md>| Some((link.reference, "".into()));
424 let mut event_iter = Parser::new_with_broken_link_callback(
425 doc,
426 main_body_opts(),
427 Some(&mut broken_link_callback),
428 );
429 let mut links = Vec::new();
430
431 let mut refids = UnordSet::default();
432
433 while let Some(event) = event_iter.next() {
434 match event {
435 Event::Start(Tag::Link { link_type, dest_url, title: _, id })
436 if may_be_doc_link(link_type) =>
437 {
438 if matches!(
439 link_type,
440 LinkType::Inline
441 | LinkType::ReferenceUnknown
442 | LinkType::Reference
443 | LinkType::Shortcut
444 | LinkType::ShortcutUnknown
445 ) {
446 if let Some(display_text) = collect_link_data(&mut event_iter) {
447 links.push(display_text);
448 }
449 }
450 if matches!(
451 link_type,
452 LinkType::Reference | LinkType::Shortcut | LinkType::Collapsed
453 ) {
454 refids.insert(id);
455 }
456
457 links.push(preprocess_link(&dest_url));
458 }
459 _ => {}
460 }
461 }
462
463 for (label, refdef) in event_iter.reference_definitions().iter().sorted_by_key(|x| x.0) {
464 if !refids.contains(label) {
465 links.push(preprocess_link(&refdef.dest));
466 }
467 }
468
469 links
470}
471
472fn collect_link_data<'input, F: BrokenLinkCallback<'input>>(
474 event_iter: &mut Parser<'input, F>,
475) -> Option<Box<str>> {
476 let mut display_text: Option<String> = None;
477 let mut append_text = |text: CowStr<'_>| {
478 if let Some(display_text) = &mut display_text {
479 display_text.push_str(&text);
480 } else {
481 display_text = Some(text.to_string());
482 }
483 };
484
485 while let Some(event) = event_iter.next() {
486 match event {
487 Event::Text(text) => {
488 append_text(text);
489 }
490 Event::Code(code) => {
491 append_text(code);
492 }
493 Event::End(_) => {
494 break;
495 }
496 _ => {}
497 }
498 }
499
500 display_text.map(String::into_boxed_str)
501}
502
503pub fn span_of_fragments(fragments: &[DocFragment]) -> Option<Span> {
505 if fragments.is_empty() {
506 return None;
507 }
508 let start = fragments[0].span;
509 if start == DUMMY_SP {
510 return None;
511 }
512 let end = fragments.last().expect("no doc strings provided").span;
513 Some(start.to(end))
514}
515
516pub fn source_span_for_markdown_range(
534 tcx: TyCtxt<'_>,
535 markdown: &str,
536 md_range: &Range<usize>,
537 fragments: &[DocFragment],
538) -> Option<Span> {
539 let map = tcx.sess.source_map();
540 source_span_for_markdown_range_inner(map, markdown, md_range, fragments)
541}
542
543pub fn source_span_for_markdown_range_inner(
545 map: &SourceMap,
546 markdown: &str,
547 md_range: &Range<usize>,
548 fragments: &[DocFragment],
549) -> Option<Span> {
550 use rustc_span::BytePos;
551
552 if let &[fragment] = &fragments
553 && fragment.kind == DocFragmentKind::RawDoc
554 && let Ok(snippet) = map.span_to_snippet(fragment.span)
555 && snippet.trim_end() == markdown.trim_end()
556 && let Ok(md_range_lo) = u32::try_from(md_range.start)
557 && let Ok(md_range_hi) = u32::try_from(md_range.end)
558 {
559 return Some(Span::new(
561 fragment.span.lo() + rustc_span::BytePos(md_range_lo),
562 fragment.span.lo() + rustc_span::BytePos(md_range_hi),
563 fragment.span.ctxt(),
564 fragment.span.parent(),
565 ));
566 }
567
568 let is_all_sugared_doc = fragments.iter().all(|frag| frag.kind == DocFragmentKind::SugaredDoc);
569
570 if !is_all_sugared_doc {
571 let mut match_data = None;
576 let pat = &markdown[md_range.clone()];
577 if pat.is_empty() {
579 return None;
580 }
581 for (i, fragment) in fragments.iter().enumerate() {
582 if let Ok(snippet) = map.span_to_snippet(fragment.span)
583 && let Some(match_start) = snippet.find(pat)
584 {
585 if match_data.is_none()
590 && !snippet.as_bytes()[match_start + 1..]
591 .windows(pat.len())
592 .any(|s| s == pat.as_bytes())
593 {
594 match_data = Some((i, match_start));
595 } else {
596 return None;
598 }
599 }
600 }
601 if let Some((i, match_start)) = match_data {
602 let sp = fragments[i].span;
603 let lo = sp.lo() + BytePos(match_start as u32);
606 return Some(
607 sp.with_lo(lo).with_hi(lo + BytePos((md_range.end - md_range.start) as u32)),
608 );
609 }
610 return None;
611 }
612
613 let snippet = map.span_to_snippet(span_of_fragments(fragments)?).ok()?;
614
615 let starting_line = markdown[..md_range.start].matches('\n').count();
616 let ending_line = starting_line + markdown[md_range.start..md_range.end].matches('\n').count();
617
618 let mut src_lines = snippet.split_terminator('\n');
621 let md_lines = markdown.split_terminator('\n');
622
623 let mut start_bytes = 0;
626 let mut end_bytes = 0;
627
628 'outer: for (line_no, md_line) in md_lines.enumerate() {
629 loop {
630 let source_line = src_lines.next()?;
631 match source_line.find(md_line) {
632 Some(offset) => {
633 if line_no == starting_line {
634 start_bytes += offset;
635
636 if starting_line == ending_line {
637 break 'outer;
638 }
639 } else if line_no == ending_line {
640 end_bytes += offset;
641 break 'outer;
642 } else if line_no < starting_line {
643 start_bytes += source_line.len() - md_line.len();
644 } else {
645 end_bytes += source_line.len() - md_line.len();
646 }
647 break;
648 }
649 None => {
650 if line_no <= starting_line {
653 start_bytes += source_line.len() + 1;
654 } else {
655 end_bytes += source_line.len() + 1;
656 }
657 }
658 }
659 }
660 }
661
662 Some(span_of_fragments(fragments)?.from_inner(InnerSpan::new(
663 md_range.start + start_bytes,
664 md_range.end + start_bytes + end_bytes,
665 )))
666}