From 336c85a053ff502fb2f42d2579fcff61efd6bdda Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Mon, 27 Dec 2021 13:44:14 -0800 Subject: [PATCH 1/3] rustdoc: Preserve rendering of macro_rules matchers when possible --- src/librustdoc/clean/utils.rs | 61 +++++++++++++++++++++++++++--- src/test/rustdoc/decl_macro.rs | 12 +++--- src/test/rustdoc/macros.rs | 8 ++-- src/test/rustdoc/reexports-priv.rs | 8 ++-- src/test/rustdoc/reexports.rs | 4 +- 5 files changed, 71 insertions(+), 22 deletions(-) diff --git a/src/librustdoc/clean/utils.rs b/src/librustdoc/clean/utils.rs index 7d5e2e36bd19..5fe7dd6c2bc8 100644 --- a/src/librustdoc/clean/utils.rs +++ b/src/librustdoc/clean/utils.rs @@ -16,6 +16,8 @@ use rustc_hir::def_id::{DefId, LOCAL_CRATE}; use rustc_middle::mir::interpret::ConstValue; use rustc_middle::ty::subst::{GenericArgKind, SubstsRef}; use rustc_middle::ty::{self, DefIdTree, TyCtxt}; +use rustc_session::parse::ParseSess; +use rustc_span::source_map::FilePathMapping; use rustc_span::symbol::{kw, sym, Symbol}; use std::fmt::Write as _; use std::mem; @@ -484,20 +486,67 @@ crate const DOC_RUST_LANG_ORG_CHANNEL: &str = env!("DOC_RUST_LANG_ORG_CHANNEL"); /// Render a sequence of macro arms in a format suitable for displaying to the user /// as part of an item declaration. pub(super) fn render_macro_arms<'a>( + cx: &DocContext<'_>, matchers: impl Iterator, arm_delim: &str, ) -> String { let mut out = String::new(); for matcher in matchers { - writeln!(out, " {} => {{ ... }}{}", render_macro_matcher(matcher), arm_delim).unwrap(); + writeln!(out, " {} => {{ ... }}{}", render_macro_matcher(cx, matcher), arm_delim) + .unwrap(); } out } /// Render a macro matcher in a format suitable for displaying to the user /// as part of an item declaration. -pub(super) fn render_macro_matcher(matcher: &TokenTree) -> String { - rustc_ast_pretty::pprust::tt_to_string(matcher) +pub(super) fn render_macro_matcher(cx: &DocContext<'_>, matcher: &TokenTree) -> String { + if let Some(snippet) = snippet_equal_to_token(cx, matcher) { + snippet + } else { + rustc_ast_pretty::pprust::tt_to_string(matcher) + } +} + +/// Find the source snippet for this token's Span, reparse it, and return the +/// snippet if the reparsed TokenTree matches the argument TokenTree. +fn snippet_equal_to_token(cx: &DocContext<'_>, matcher: &TokenTree) -> Option { + // Find what rustc thinks is the source snippet. + // This may not actually be anything meaningful if this matcher was itself + // generated by a macro. + let source_map = cx.sess().source_map(); + let span = matcher.span(); + let snippet = source_map.span_to_snippet(span).ok()?; + + // Create a Parser. + let sess = ParseSess::new(FilePathMapping::empty()); + let file_name = source_map.span_to_filename(span); + let mut parser = + match rustc_parse::maybe_new_parser_from_source_str(&sess, file_name, snippet.clone()) { + Ok(parser) => parser, + Err(diagnostics) => { + for mut diagnostic in diagnostics { + diagnostic.cancel(); + } + return None; + } + }; + + // Reparse a single token tree. + let mut reparsed_trees = match parser.parse_all_token_trees() { + Ok(reparsed_trees) => reparsed_trees, + Err(mut diagnostic) => { + diagnostic.cancel(); + return None; + } + }; + if reparsed_trees.len() != 1 { + return None; + } + let reparsed_tree = reparsed_trees.pop().unwrap(); + + // Compare against the original tree. + if reparsed_tree.eq_unspanned(matcher) { Some(snippet) } else { None } } pub(super) fn display_macro_source( @@ -512,21 +561,21 @@ pub(super) fn display_macro_source( let matchers = tts.chunks(4).map(|arm| &arm[0]); if def.macro_rules { - format!("macro_rules! {} {{\n{}}}", name, render_macro_arms(matchers, ";")) + format!("macro_rules! {} {{\n{}}}", name, render_macro_arms(cx, matchers, ";")) } else { if matchers.len() <= 1 { format!( "{}macro {}{} {{\n ...\n}}", vis.to_src_with_space(cx.tcx, def_id), name, - matchers.map(render_macro_matcher).collect::(), + matchers.map(|matcher| render_macro_matcher(cx, matcher)).collect::(), ) } else { format!( "{}macro {} {{\n{}}}", vis.to_src_with_space(cx.tcx, def_id), name, - render_macro_arms(matchers, ","), + render_macro_arms(cx, matchers, ","), ) } } diff --git a/src/test/rustdoc/decl_macro.rs b/src/test/rustdoc/decl_macro.rs index fe19dadbe024..94ade31b5e5f 100644 --- a/src/test/rustdoc/decl_macro.rs +++ b/src/test/rustdoc/decl_macro.rs @@ -9,7 +9,7 @@ pub macro my_macro() { } -// @has decl_macro/macro.my_macro_2.html //pre 'pub macro my_macro_2($($tok : tt) *) {' +// @has decl_macro/macro.my_macro_2.html //pre 'pub macro my_macro_2($($tok:tt)*) {' // @has - //pre '...' // @has - //pre '}' pub macro my_macro_2($($tok:tt)*) { @@ -18,8 +18,8 @@ pub macro my_macro_2($($tok:tt)*) { // @has decl_macro/macro.my_macro_multi.html //pre 'pub macro my_macro_multi {' // @has - //pre '(_) => { ... },' -// @has - //pre '($foo : ident.$bar : expr) => { ... },' -// @has - //pre '($($foo : literal), +) => { ... },' +// @has - //pre '($foo:ident . $bar:expr) => { ... },' +// @has - //pre '($($foo:literal),+) => { ... },' // @has - //pre '}' pub macro my_macro_multi { (_) => { @@ -33,7 +33,7 @@ pub macro my_macro_multi { } } -// @has decl_macro/macro.by_example_single.html //pre 'pub macro by_example_single($foo : expr) {' +// @has decl_macro/macro.by_example_single.html //pre 'pub macro by_example_single($foo:expr) {' // @has - //pre '...' // @has - //pre '}' pub macro by_example_single { @@ -42,12 +42,12 @@ pub macro by_example_single { mod a { mod b { - // @has decl_macro/a/b/macro.by_example_vis.html //pre 'pub(super) macro by_example_vis($foo : expr) {' + // @has decl_macro/a/b/macro.by_example_vis.html //pre 'pub(super) macro by_example_vis($foo:expr) {' pub(in super) macro by_example_vis { ($foo:expr) => {} } mod c { - // @has decl_macro/a/b/c/macro.by_example_vis_named.html //pre 'pub(in a) macro by_example_vis_named($foo : expr) {' + // @has decl_macro/a/b/c/macro.by_example_vis_named.html //pre 'pub(in a) macro by_example_vis_named($foo:expr) {' pub(in a) macro by_example_vis_named { ($foo:expr) => {} } diff --git a/src/test/rustdoc/macros.rs b/src/test/rustdoc/macros.rs index 1cd454720e7d..ae0cf7a14789 100644 --- a/src/test/rustdoc/macros.rs +++ b/src/test/rustdoc/macros.rs @@ -1,7 +1,7 @@ // @has macros/macro.my_macro.html //pre 'macro_rules! my_macro {' // @has - //pre '() => { ... };' -// @has - //pre '($a : tt) => { ... };' -// @has - //pre '($e : expr) => { ... };' +// @has - //pre '($a:tt) => { ... };' +// @has - //pre '($e:expr) => { ... };' #[macro_export] macro_rules! my_macro { () => []; @@ -12,8 +12,8 @@ macro_rules! my_macro { // Check that exported macro defined in a module are shown at crate root. // @has macros/macro.my_sub_macro.html //pre 'macro_rules! my_sub_macro {' // @has - //pre '() => { ... };' -// @has - //pre '($a : tt) => { ... };' -// @has - //pre '($e : expr) => { ... };' +// @has - //pre '($a:tt) => { ... };' +// @has - //pre '($e:expr) => { ... };' mod sub { #[macro_export] macro_rules! my_sub_macro { diff --git a/src/test/rustdoc/reexports-priv.rs b/src/test/rustdoc/reexports-priv.rs index 95f741807494..aea9b9f2b395 100644 --- a/src/test/rustdoc/reexports-priv.rs +++ b/src/test/rustdoc/reexports-priv.rs @@ -5,7 +5,7 @@ extern crate reexports; -// @has 'foo/macro.addr_of.html' '//*[@class="docblock item-decl"]' 'pub macro addr_of($place : expr) {' +// @has 'foo/macro.addr_of.html' '//*[@class="docblock item-decl"]' 'pub macro addr_of($place:expr) {' pub use reexports::addr_of; // @!has 'foo/macro.addr_of_crate.html' pub(crate) use reexports::addr_of_crate; @@ -61,11 +61,11 @@ use reexports::UnionLocal; pub mod outer { pub mod inner { - // @has 'foo/outer/inner/macro.addr_of.html' '//*[@class="docblock item-decl"]' 'pub macro addr_of($place : expr) {' + // @has 'foo/outer/inner/macro.addr_of.html' '//*[@class="docblock item-decl"]' 'pub macro addr_of($place:expr) {' pub use reexports::addr_of; - // @has 'foo/outer/inner/macro.addr_of_crate.html' '//*[@class="docblock item-decl"]' 'pub(crate) macro addr_of_crate($place : expr) {' + // @has 'foo/outer/inner/macro.addr_of_crate.html' '//*[@class="docblock item-decl"]' 'pub(crate) macro addr_of_crate($place:expr) {' pub(crate) use reexports::addr_of_crate; - // @has 'foo/outer/inner/macro.addr_of_super.html' '//*[@class="docblock item-decl"]' 'pub(in outer) macro addr_of_super($place : expr) {' + // @has 'foo/outer/inner/macro.addr_of_super.html' '//*[@class="docblock item-decl"]' 'pub(in outer) macro addr_of_super($place:expr) {' pub(super) use reexports::addr_of_super; // @!has 'foo/outer/inner/macro.addr_of_self.html' pub(self) use reexports::addr_of_self; diff --git a/src/test/rustdoc/reexports.rs b/src/test/rustdoc/reexports.rs index 3b3153084703..7abcbfb61812 100644 --- a/src/test/rustdoc/reexports.rs +++ b/src/test/rustdoc/reexports.rs @@ -4,7 +4,7 @@ extern crate reexports; -// @has 'foo/macro.addr_of.html' '//*[@class="docblock item-decl"]' 'pub macro addr_of($place : expr) {' +// @has 'foo/macro.addr_of.html' '//*[@class="docblock item-decl"]' 'pub macro addr_of($place:expr) {' pub use reexports::addr_of; // @!has 'foo/macro.addr_of_crate.html' pub(crate) use reexports::addr_of_crate; @@ -60,7 +60,7 @@ use reexports::UnionLocal; pub mod outer { pub mod inner { - // @has 'foo/outer/inner/macro.addr_of.html' '//*[@class="docblock item-decl"]' 'pub macro addr_of($place : expr) {' + // @has 'foo/outer/inner/macro.addr_of.html' '//*[@class="docblock item-decl"]' 'pub macro addr_of($place:expr) {' pub use reexports::addr_of; // @!has 'foo/outer/inner/macro.addr_of_crate.html' pub(crate) use reexports::addr_of_crate; From 544a6bb7e72c907f05881ae7f461005cc5f92759 Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Tue, 28 Dec 2021 13:43:08 -0800 Subject: [PATCH 2/3] Replace &DocCtxt -> TyCtxt in macro matcher rendering --- src/librustdoc/clean/utils.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/librustdoc/clean/utils.rs b/src/librustdoc/clean/utils.rs index 5fe7dd6c2bc8..2c3fd39baf69 100644 --- a/src/librustdoc/clean/utils.rs +++ b/src/librustdoc/clean/utils.rs @@ -486,13 +486,13 @@ crate const DOC_RUST_LANG_ORG_CHANNEL: &str = env!("DOC_RUST_LANG_ORG_CHANNEL"); /// Render a sequence of macro arms in a format suitable for displaying to the user /// as part of an item declaration. pub(super) fn render_macro_arms<'a>( - cx: &DocContext<'_>, + tcx: TyCtxt<'_>, matchers: impl Iterator, arm_delim: &str, ) -> String { let mut out = String::new(); for matcher in matchers { - writeln!(out, " {} => {{ ... }}{}", render_macro_matcher(cx, matcher), arm_delim) + writeln!(out, " {} => {{ ... }}{}", render_macro_matcher(tcx, matcher), arm_delim) .unwrap(); } out @@ -500,8 +500,8 @@ pub(super) fn render_macro_arms<'a>( /// Render a macro matcher in a format suitable for displaying to the user /// as part of an item declaration. -pub(super) fn render_macro_matcher(cx: &DocContext<'_>, matcher: &TokenTree) -> String { - if let Some(snippet) = snippet_equal_to_token(cx, matcher) { +pub(super) fn render_macro_matcher(tcx: TyCtxt<'_>, matcher: &TokenTree) -> String { + if let Some(snippet) = snippet_equal_to_token(tcx, matcher) { snippet } else { rustc_ast_pretty::pprust::tt_to_string(matcher) @@ -510,11 +510,11 @@ pub(super) fn render_macro_matcher(cx: &DocContext<'_>, matcher: &TokenTree) -> /// Find the source snippet for this token's Span, reparse it, and return the /// snippet if the reparsed TokenTree matches the argument TokenTree. -fn snippet_equal_to_token(cx: &DocContext<'_>, matcher: &TokenTree) -> Option { +fn snippet_equal_to_token(tcx: TyCtxt<'_>, matcher: &TokenTree) -> Option { // Find what rustc thinks is the source snippet. // This may not actually be anything meaningful if this matcher was itself // generated by a macro. - let source_map = cx.sess().source_map(); + let source_map = tcx.sess.source_map(); let span = matcher.span(); let snippet = source_map.span_to_snippet(span).ok()?; @@ -561,21 +561,21 @@ pub(super) fn display_macro_source( let matchers = tts.chunks(4).map(|arm| &arm[0]); if def.macro_rules { - format!("macro_rules! {} {{\n{}}}", name, render_macro_arms(cx, matchers, ";")) + format!("macro_rules! {} {{\n{}}}", name, render_macro_arms(cx.tcx, matchers, ";")) } else { if matchers.len() <= 1 { format!( "{}macro {}{} {{\n ...\n}}", vis.to_src_with_space(cx.tcx, def_id), name, - matchers.map(|matcher| render_macro_matcher(cx, matcher)).collect::(), + matchers.map(|matcher| render_macro_matcher(cx.tcx, matcher)).collect::(), ) } else { format!( "{}macro {} {{\n{}}}", vis.to_src_with_space(cx.tcx, def_id), name, - render_macro_arms(cx, matchers, ","), + render_macro_arms(cx.tcx, matchers, ","), ) } } From 0f8415b8e1d93de7b6673298c9f10c709742d9ab Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Tue, 28 Dec 2021 13:52:33 -0800 Subject: [PATCH 3/3] Add a test of rustdoc on macro-generated macro --- src/test/rustdoc/macro-generated-macro.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 src/test/rustdoc/macro-generated-macro.rs diff --git a/src/test/rustdoc/macro-generated-macro.rs b/src/test/rustdoc/macro-generated-macro.rs new file mode 100644 index 000000000000..25d8bc3ec628 --- /dev/null +++ b/src/test/rustdoc/macro-generated-macro.rs @@ -0,0 +1,14 @@ +macro_rules! outer { + ($($matcher:tt)*) => { + #[macro_export] + macro_rules! inner { + (<= $($matcher)* =>) => {}; + } + } +} + +// @has macro_generated_macro/macro.inner.html //pre 'macro_rules! inner {' +// @has - //pre '(<= type $($i : ident) :: * + $e : expr =>) => { ... };' +outer!(type $($i:ident)::* + $e:expr); + +inner!(<= type foo::bar + x.sort() =>);