diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index c701a0e2919..51f365be922 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -458,7 +458,13 @@ Calculating code examples follows these rules: ### `--with-examples`: include examples of uses of items as documentation -This option, combined with `--scrape-examples-target-crate` and `--scrape-examples-output-path`, is used to implement the functionality in [RFC #3123](https://github.com/rust-lang/rfcs/pull/3123). Uses of an item (currently functions / call-sites) are found in a crate and its reverse-dependencies, and then the uses are included as documentation for that item. This feature is intended to be used via `cargo doc --scrape-examples`, but the rustdoc-only workflow looks like: +This option, combined with `--scrape-examples-target-crate` and +`--scrape-examples-output-path`, is used to implement the functionality in [RFC +#3123](https://github.com/rust-lang/rfcs/pull/3123). Uses of an item (currently +functions / call-sites) are found in a crate and its reverse-dependencies, and +then the uses are included as documentation for that item. This feature is +intended to be used via `cargo doc --scrape-examples`, but the rustdoc-only +workflow looks like: ```bash $ rustdoc examples/ex.rs -Z unstable-options \ @@ -468,4 +474,8 @@ $ rustdoc examples/ex.rs -Z unstable-options \ $ rustdoc src/lib.rs -Z unstable-options --with-examples output.calls ``` -First, the library must be checked to generate an `rmeta`. Then a reverse-dependency like `examples/ex.rs` is given to rustdoc with the target crate being documented (`foobar`) and a path to output the calls (`output.calls`). Then, the generated calls file can be passed via `--with-examples` to the subsequent documentation of `foobar`. +First, the library must be checked to generate an `rmeta`. Then a +reverse-dependency like `examples/ex.rs` is given to rustdoc with the target +crate being documented (`foobar`) and a path to output the calls +(`output.calls`). Then, the generated calls file can be passed via +`--with-examples` to the subsequent documentation of `foobar`. diff --git a/src/librustdoc/clean/inline.rs b/src/librustdoc/clean/inline.rs index 9d5a95a88a2..4a888b22332 100644 --- a/src/librustdoc/clean/inline.rs +++ b/src/librustdoc/clean/inline.rs @@ -235,7 +235,6 @@ fn build_external_function(cx: &mut DocContext<'_>, did: DefId) -> clean::Functi decl, generics, header: hir::FnHeader { unsafety: sig.unsafety(), abi: sig.abi(), constness, asyncness }, - def_id: did, } } diff --git a/src/librustdoc/clean/mod.rs b/src/librustdoc/clean/mod.rs index 409dc914597..23307eb48c6 100644 --- a/src/librustdoc/clean/mod.rs +++ b/src/librustdoc/clean/mod.rs @@ -801,8 +801,7 @@ impl<'a> Clean for (&'a hir::FnSig<'a>, &'a hir::Generics<'a>, hir::Bo fn clean(&self, cx: &mut DocContext<'_>) -> Function { let (generics, decl) = enter_impl_trait(cx, |cx| (self.1.clean(cx), (&*self.0.decl, self.2).clean(cx))); - let def_id = self.2.hir_id.owner.to_def_id(); - Function { decl, generics, header: self.0.header, def_id } + Function { decl, generics, header: self.0.header } } } @@ -934,8 +933,7 @@ impl Clean for hir::TraitItem<'_> { let (generics, decl) = enter_impl_trait(cx, |cx| { (self.generics.clean(cx), (&*sig.decl, &names[..]).clean(cx)) }); - let def_id = self.def_id.to_def_id(); - let mut t = Function { header: sig.header, decl, generics, def_id }; + let mut t = Function { header: sig.header, decl, generics }; if t.header.constness == hir::Constness::Const && is_unstable_const_fn(cx.tcx, local_did).is_some() { @@ -1069,7 +1067,6 @@ impl Clean for ty::AssocItem { constness, asyncness, }, - def_id: self.def_id, }, defaultness, ) @@ -1083,7 +1080,6 @@ impl Clean for ty::AssocItem { constness: hir::Constness::NotConst, asyncness: hir::IsAsync::NotAsync, }, - def_id: self.def_id, }) } } @@ -2103,7 +2099,6 @@ impl Clean for (&hir::ForeignItem<'_>, Option) { constness: hir::Constness::NotConst, asyncness: hir::IsAsync::NotAsync, }, - def_id, }) } hir::ForeignItemKind::Static(ref ty, mutability) => { diff --git a/src/librustdoc/clean/types.rs b/src/librustdoc/clean/types.rs index 043ffbfd187..0e78fe7aec3 100644 --- a/src/librustdoc/clean/types.rs +++ b/src/librustdoc/clean/types.rs @@ -1254,7 +1254,6 @@ crate struct Function { crate decl: FnDecl, crate generics: Generics, crate header: hir::FnHeader, - crate def_id: DefId, } #[derive(Clone, PartialEq, Eq, Debug, Hash)] diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index 3a4c6891708..25ec28302f7 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -597,11 +597,10 @@ fn document_full_inner( clean::ItemKind::StrippedItem(box kind) | kind => kind, }; - match kind { - clean::ItemKind::FunctionItem(f) | clean::ItemKind::MethodItem(f, _) => { - render_call_locations(w, cx, f.def_id, item); + if let clean::ItemKind::FunctionItem(..) | clean::ItemKind::MethodItem(..) = kind { + if let Some(def_id) = item.def_id.as_def_id() { + render_call_locations(w, cx, def_id, item); } - _ => {} } } diff --git a/src/librustdoc/json/conversions.rs b/src/librustdoc/json/conversions.rs index b151f62c1bf..731fc4ff3ce 100644 --- a/src/librustdoc/json/conversions.rs +++ b/src/librustdoc/json/conversions.rs @@ -289,7 +289,7 @@ crate fn from_fn_header(header: &rustc_hir::FnHeader) -> HashSet { impl FromWithTcx for Function { fn from_tcx(function: clean::Function, tcx: TyCtxt<'_>) -> Self { - let clean::Function { decl, generics, header, def_id: _ } = function; + let clean::Function { decl, generics, header } = function; Function { decl: decl.into_tcx(tcx), generics: generics.into_tcx(tcx), @@ -530,7 +530,7 @@ crate fn from_function_method( has_body: bool, tcx: TyCtxt<'_>, ) -> Method { - let clean::Function { header, decl, generics, def_id: _ } = function; + let clean::Function { header, decl, generics } = function; Method { decl: decl.into_tcx(tcx), generics: generics.into_tcx(tcx), diff --git a/src/test/rustdoc-ui/scrape-examples-wrong-options-1.rs b/src/test/rustdoc-ui/scrape-examples-wrong-options-1.rs new file mode 100644 index 00000000000..a1f005c32ee --- /dev/null +++ b/src/test/rustdoc-ui/scrape-examples-wrong-options-1.rs @@ -0,0 +1 @@ +// compile-flags: -Z unstable-options --scrape-examples-target-crate foobar diff --git a/src/test/rustdoc-ui/scrape-examples-wrong-options-1.stderr b/src/test/rustdoc-ui/scrape-examples-wrong-options-1.stderr new file mode 100644 index 00000000000..eb8e9f79968 --- /dev/null +++ b/src/test/rustdoc-ui/scrape-examples-wrong-options-1.stderr @@ -0,0 +1,2 @@ +error: must use --scrape-examples-output-path and --scrape-examples-target-crate together + diff --git a/src/test/rustdoc-ui/scrape-examples-wrong-options-2.rs b/src/test/rustdoc-ui/scrape-examples-wrong-options-2.rs new file mode 100644 index 00000000000..4aacec7f094 --- /dev/null +++ b/src/test/rustdoc-ui/scrape-examples-wrong-options-2.rs @@ -0,0 +1 @@ +// compile-flags: -Z unstable-options --scrape-examples-output-path ex.calls diff --git a/src/test/rustdoc-ui/scrape-examples-wrong-options-2.stderr b/src/test/rustdoc-ui/scrape-examples-wrong-options-2.stderr new file mode 100644 index 00000000000..eb8e9f79968 --- /dev/null +++ b/src/test/rustdoc-ui/scrape-examples-wrong-options-2.stderr @@ -0,0 +1,2 @@ +error: must use --scrape-examples-output-path and --scrape-examples-target-crate together + diff --git a/src/test/rustdoc-ui/scrape-examples-wrong-options.rs b/src/test/rustdoc-ui/scrape-examples-wrong-options.rs deleted file mode 100644 index b18d4715453..00000000000 --- a/src/test/rustdoc-ui/scrape-examples-wrong-options.rs +++ /dev/null @@ -1 +0,0 @@ -// compile-flags: --scrape-examples-target-crate foobar diff --git a/src/test/rustdoc-ui/scrape-examples-wrong-options.stderr b/src/test/rustdoc-ui/scrape-examples-wrong-options.stderr deleted file mode 100644 index b4ad28f92da..00000000000 --- a/src/test/rustdoc-ui/scrape-examples-wrong-options.stderr +++ /dev/null @@ -1,2 +0,0 @@ -error: the `-Z unstable-options` flag must also be passed to enable the flag `scrape-examples-target-crate` -