From 82bd146d60425c3cd0c99892742f1454f5eb8191 Mon Sep 17 00:00:00 2001 From: QuietMisdreavus Date: Wed, 14 Mar 2018 16:40:28 -0500 Subject: [PATCH] talk about doc(masked) --- src/doc/rustdoc/src/unstable-features.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index 167022395244..9f0476d4eef7 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -148,3 +148,23 @@ chapter in the Unstable Book][unstable-spotlight] and [its tracking issue][issue [unstable-spotlight]: ../unstable-book/language-features/doc-spotlight.html [issue-spotlight]: https://github.com/rust-lang/rust/issues/45040 + +## Exclude certain dependencies from documentation + +The standard library uses several dependencies which, in turn, use several types and traits from the +standard library. In addition, there are several compiler-internal crates that are not considered to +be part of the official standard library, and thus would be a distraction to include in +documentation. It's not enough to exclude their crate documentation, since information about trait +implementations appears on the pages for both the type and the trait, which can be in different +crates! + +To prevent internal types from being included in documentation, the standard library adds an +attribute to their `extern crate` declarations: `#[doc(masked)]`. This causes Rustdoc to "mask out" +types from these crates when building lists of trait implementations. + +The `#[doc(masked)]` attribute is intended to be used internally, and is governed by a feature gate. +For more information, see [its chapter in the Unstable Book][unstable-masked] and [its tracking +issue][issue-masked]. + +[unstable-masked]: ../unstable-book/language-features/doc-masked.html +[issue-masked]: https://github.com/rust-lang/rust/issues/44027