Add support to generate documentation for tests

The new option --document-tests is unstable and documented as such.
In order to use it is needed to add `--cfg test` and in case the tests
are not marked public to add `--document-private-items`.
The implementation hide the auto generate main test function and
constants.

Author: ifxfrancois

src/doc/rustdoc/src/unstable-features.md

@@ -664,3 +664,34 @@ Similar to cargo `build.rustc-wrapper` option, this flag takes a `rustc` wrapper
 The first argument to the program will be the test builder program.
 
 This flag can be passed multiple times to nest wrappers.
+
+### `--document-tests`: show test items
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs -Z unstable-options --cfg test --document-private-items --document-tests
+```
+
+By default, `rustdoc` does not document test items.
+
+```rust
+/// by default this test function would not be documented
+#[test]
+fn test_in_module() {
+     assert_eq!(2, 1 + 1);
+}
+/// by default this test module would not be documented
+#[cfg(test)]
+mod tests {
+    /// by default this test function would not be documented
+    #[test]
+    fn test_in_a_test_module() {
+        assert_eq!(2, 1 + 1);
+    }
+}
+```
+
+Note:
+* `--cfg test` must be set because tests are guarded by #[cfg(test)].
+* `--document-private-items` is typically required because it is standard practice to keep test items private. By enabling this option, you ensure that private items, including tests, are documented as needed while maintaining their non-public status.

src/librustdoc/clean/mod.rs

@@ -1028,7 +1028,11 @@ fn clean_fn_or_proc_macro<'tcx>(
         None => {
             let mut func = clean_function(cx, sig, generics, FunctionArgs::Body(body_id));
             clean_fn_decl_legacy_const_generics(&mut func, attrs);
-            FunctionItem(func)
+            if cx.cache.document_tests && cx.cache.tests.contains(&item.owner_id.to_def_id()) {
+                TestItem(func)
+            } else {
+                FunctionItem(func)
+            }
         }
     }
 }

src/librustdoc/clean/types.rs

@@ -671,7 +671,8 @@ impl Item {
             }
             ItemKind::FunctionItem(_)
             | ItemKind::MethodItem(_, _)
-            | ItemKind::RequiredMethodItem(_) => {
+            | ItemKind::RequiredMethodItem(_)
+            | ItemKind::TestItem(_) => {
                 let def_id = self.def_id().unwrap();
                 build_fn_header(def_id, tcx, tcx.asyncness(def_id))
             }
@@ -845,6 +846,7 @@ pub(crate) enum ItemKind {
     UnionItem(Union),
     EnumItem(Enum),
     FunctionItem(Box<Function>),
+    TestItem(Box<Function>),
     ModuleItem(Module),
     TypeAliasItem(Box<TypeAlias>),
     StaticItem(Static),
@@ -905,6 +907,7 @@ impl ItemKind {
             ExternCrateItem { .. }
             | ImportItem(_)
             | FunctionItem(_)
+            | TestItem(_)
             | TypeAliasItem(_)
             | StaticItem(_)
             | ConstantItem(_)

src/librustdoc/clean/types/tests.rs

@@ -71,7 +71,7 @@ fn should_not_trim() {
 fn is_same_generic() {
     use crate::clean::types::{PrimitiveType, Type};
     use crate::formats::cache::Cache;
-    let cache = Cache::new(false, false);
+    let cache = Cache::new(false, false, false);
     let generic = Type::Generic(rustc_span::symbol::sym::Any);
     let unit = Type::Primitive(PrimitiveType::Unit);
     assert!(!generic.is_doc_subtype_of(&unit, &cache));

src/librustdoc/config.rs

@@ -275,6 +275,8 @@ pub(crate) struct RenderOptions {
     pub(crate) document_private: bool,
     /// Document items that have `doc(hidden)`.
     pub(crate) document_hidden: bool,
+    /// Document tests.
+    pub(crate) document_tests: bool,
     /// If `true`, generate a JSON file in the crate folder instead of HTML redirection files.
     pub(crate) generate_redirect_map: bool,
     /// Show the memory layout of types in the docs.
@@ -772,6 +774,7 @@ impl Options {
         }
 
         let scrape_examples_options = ScrapeExamplesOptions::new(matches, dcx);
+        let document_tests = matches.opt_present("document-tests");
         let with_examples = matches.opt_strs("with-examples");
         let call_locations = crate::scrape_examples::load_call_locations(with_examples, dcx);
 
@@ -840,6 +843,7 @@ impl Options {
             markdown_playground_url,
             document_private,
             document_hidden,
+            document_tests,
             generate_redirect_map,
             show_type_layout,
             unstable_features,

src/librustdoc/core.rs

@@ -220,7 +220,7 @@ pub(crate) fn create_config(
         remap_path_prefix,
         ..
     }: RustdocOptions,
-    RenderOptions { document_private, .. }: &RenderOptions,
+    RenderOptions { document_private, document_tests, .. }: &RenderOptions,
     using_internal_features: Arc<AtomicBool>,
 ) -> rustc_interface::Config {
     // Add the doc cfg into the doc build.
@@ -249,7 +249,8 @@ pub(crate) fn create_config(
         if proc_macro_crate { vec![CrateType::ProcMacro] } else { vec![CrateType::Rlib] };
     let resolve_doc_links =
         if *document_private { ResolveDocLinks::All } else { ResolveDocLinks::Exported };
-    let test = scrape_examples_options.map(|opts| opts.scrape_tests).unwrap_or(false);
+    let test = scrape_examples_options.map(|opts| opts.scrape_tests).unwrap_or(false)
+        || (cfgs.iter().any(|cfg| cfg == "test") && *document_tests);
     // plays with error output here!
     let sessopts = config::Options {
         maybe_sysroot,
@@ -361,7 +362,11 @@ pub(crate) fn run_global_ctxt(
         impl_trait_bounds: Default::default(),
         generated_synthetics: Default::default(),
         auto_traits,
-        cache: Cache::new(render_options.document_private, render_options.document_hidden),
+        cache: Cache::new(
+            render_options.document_private,
+            render_options.document_hidden,
+            render_options.document_tests,
+        ),
         inlined: FxHashSet::default(),
         output_format,
         render_options,

src/librustdoc/fold.rs

@@ -79,6 +79,7 @@ pub(crate) trait DocFolder: Sized {
             ExternCrateItem { src: _ }
             | ImportItem(_)
             | FunctionItem(_)
+            | TestItem(_)
             | StaticItem(_)
             | ConstantItem(..)
             | TraitAliasItem(_)

src/librustdoc/formats/cache.rs

@@ -91,6 +91,11 @@ pub(crate) struct Cache {
     /// Whether to document hidden items.
     /// This is stored in `Cache` so it doesn't need to be passed through all rustdoc functions.
     pub(crate) document_hidden: bool,
+    /// Whether to document tests.
+    /// This is stored in `Cache` so it doesn't need to be passed through all rustdoc functions.
+    pub(crate) document_tests: bool,
+    /// DefIds of all functions which are tests.
+    pub(crate) tests: FxHashSet<DefId>,
 
     /// Crates marked with [`#[doc(masked)]`][doc_masked].
     ///
@@ -142,8 +147,8 @@ struct CacheBuilder<'a, 'tcx> {
 }
 
 impl Cache {
-    pub(crate) fn new(document_private: bool, document_hidden: bool) -> Self {
-        Cache { document_private, document_hidden, ..Cache::default() }
+    pub(crate) fn new(document_private: bool, document_hidden: bool, document_tests: bool) -> Self {
+        Cache { document_private, document_hidden, document_tests, ..Cache::default() }
     }
 
     /// Populates the `Cache` with more data. The returned `Crate` will be missing some data that was
@@ -295,6 +300,7 @@ impl DocFolder for CacheBuilder<'_, '_> {
             | clean::TraitItem(..)
             | clean::TraitAliasItem(..)
             | clean::FunctionItem(..)
+            | clean::TestItem(..)
             | clean::ModuleItem(..)
             | clean::ForeignFunctionItem(..)
             | clean::ForeignStaticItem(..)

src/librustdoc/formats/item_type.rs

@@ -57,6 +57,7 @@ pub(crate) enum ItemType {
     TraitAlias = 25,
     // This number is reserved for use in JavaScript
     // Generic = 26,
+    Test = 27,
 }
 
 impl Serialize for ItemType {
@@ -83,6 +84,7 @@ impl<'a> From<&'a clean::Item> for ItemType {
             clean::UnionItem(..) => ItemType::Union,
             clean::EnumItem(..) => ItemType::Enum,
             clean::FunctionItem(..) => ItemType::Function,
+            clean::TestItem(..) => ItemType::Test,
             clean::TypeAliasItem(..) => ItemType::TypeAlias,
             clean::StaticItem(..) => ItemType::Static,
             clean::ConstantItem(..) => ItemType::Constant,
@@ -178,6 +180,7 @@ impl ItemType {
             ItemType::Union => "union",
             ItemType::Enum => "enum",
             ItemType::Function => "fn",
+            ItemType::Test => "test",
             ItemType::TypeAlias => "type",
             ItemType::Static => "static",
             ItemType::Trait => "trait",

src/librustdoc/html/render/mod.rs

@@ -342,6 +342,7 @@ struct AllTypes {
     attribute_macros: FxIndexSet<ItemEntry>,
     derive_macros: FxIndexSet<ItemEntry>,
     trait_aliases: FxIndexSet<ItemEntry>,
+    tests: FxIndexSet<ItemEntry>,
 }
 
 impl AllTypes {
@@ -361,6 +362,7 @@ impl AllTypes {
             attribute_macros: new_set(100),
             derive_macros: new_set(100),
             trait_aliases: new_set(100),
+            tests: new_set(100),
         }
     }
 
@@ -386,6 +388,7 @@ impl AllTypes {
                 }
                 ItemType::ProcDerive => self.derive_macros.insert(ItemEntry::new(new_url, name)),
                 ItemType::TraitAlias => self.trait_aliases.insert(ItemEntry::new(new_url, name)),
+                ItemType::Test => self.tests.insert(ItemEntry::new(new_url, name)),
                 _ => true,
             };
         }
@@ -415,6 +418,9 @@ impl AllTypes {
         if !self.functions.is_empty() {
             sections.insert(ItemSection::Functions);
         }
+        if !self.tests.is_empty() {
+            sections.insert(ItemSection::Tests);
+        }
         if !self.type_aliases.is_empty() {
             sections.insert(ItemSection::TypeAliases);
         }
@@ -433,6 +439,9 @@ impl AllTypes {
         if !self.trait_aliases.is_empty() {
             sections.insert(ItemSection::TraitAliases);
         }
+        if !self.tests.is_empty() {
+            sections.insert(ItemSection::Tests);
+        }
 
         sections
     }
@@ -469,6 +478,7 @@ impl AllTypes {
         print_entries(f, &self.attribute_macros, ItemSection::AttributeMacros);
         print_entries(f, &self.derive_macros, ItemSection::DeriveMacros);
         print_entries(f, &self.functions, ItemSection::Functions);
+        print_entries(f, &self.tests, ItemSection::Tests);
         print_entries(f, &self.type_aliases, ItemSection::TypeAliases);
         print_entries(f, &self.trait_aliases, ItemSection::TraitAliases);
         print_entries(f, &self.statics, ItemSection::Statics);
@@ -2268,6 +2278,7 @@ pub(crate) enum ItemSection {
     Statics,
     Traits,
     Functions,
+    Tests,
     TypeAliases,
     Unions,
     Implementations,
@@ -2300,6 +2311,7 @@ impl ItemSection {
             Statics,
             Traits,
             Functions,
+            Tests,
             TypeAliases,
             Unions,
             Implementations,
@@ -2325,6 +2337,7 @@ impl ItemSection {
             Self::Unions => "unions",
             Self::Enums => "enums",
             Self::Functions => "functions",
+            Self::Tests => "tests",
             Self::TypeAliases => "types",
             Self::Statics => "statics",
             Self::Constants => "constants",
@@ -2354,6 +2367,7 @@ impl ItemSection {
             Self::Unions => "Unions",
             Self::Enums => "Enums",
             Self::Functions => "Functions",
+            Self::Tests => "Tests",
             Self::TypeAliases => "Type Aliases",
             Self::Statics => "Statics",
             Self::Constants => "Constants",
@@ -2384,6 +2398,7 @@ fn item_ty_to_section(ty: ItemType) -> ItemSection {
         ItemType::Union => ItemSection::Unions,
         ItemType::Enum => ItemSection::Enums,
         ItemType::Function => ItemSection::Functions,
+        ItemType::Test => ItemSection::Tests,
         ItemType::TypeAlias => ItemSection::TypeAliases,
         ItemType::Static => ItemSection::Statics,
         ItemType::Constant => ItemSection::Constants,

src/librustdoc/html/render/print_item.rs

@@ -184,6 +184,7 @@ pub(super) fn print_item(cx: &Context<'_>, item: &clean::Item, buf: &mut Buffer)
             }
         }
         clean::FunctionItem(..) | clean::ForeignFunctionItem(..) => "Function ",
+        clean::TestItem(..) => "Test ",
         clean::TraitItem(..) => "Trait ",
         clean::StructItem(..) => "Struct ",
         clean::UnionItem(..) => "Union ",
@@ -251,9 +252,9 @@ pub(super) fn print_item(cx: &Context<'_>, item: &clean::Item, buf: &mut Buffer)
 
     match &item.kind {
         clean::ModuleItem(ref m) => item_module(buf, cx, item, &m.items),
-        clean::FunctionItem(ref f) | clean::ForeignFunctionItem(ref f, _) => {
-            item_function(buf, cx, item, f)
-        }
+        clean::FunctionItem(ref f)
+        | clean::ForeignFunctionItem(ref f, _)
+        | clean::TestItem(ref f) => item_function(buf, cx, item, f),
         clean::TraitItem(ref t) => item_trait(buf, cx, item, t),
         clean::StructItem(ref s) => item_struct(buf, cx, item, s),
         clean::UnionItem(ref s) => item_union(buf, cx, item, s),
@@ -330,6 +331,7 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
             ItemType::Static => 8,
             ItemType::Trait => 9,
             ItemType::Function => 10,
+            ItemType::Test => 11,
             ItemType::TypeAlias => 12,
             ItemType::Union => 13,
             _ => 14 + ty as u8,

src/librustdoc/html/static/js/main.js

@@ -581,6 +581,7 @@ function preLoadCss(cssUrl) {
             block("static", "static", "Statics");
             block("trait", "traits", "Traits");
             block("fn", "functions", "Functions");
+            block("test", "tests", "Tests");
             block("type", "types", "Type Aliases");
             block("union", "unions", "Unions");
             // No point, because these items don't appear in modules

src/librustdoc/json/conversions.rs

@@ -312,7 +312,9 @@ fn from_clean_item(item: clean::Item, renderer: &JsonRenderer<'_>) -> ItemEnum {
         StructFieldItem(f) => ItemEnum::StructField(f.into_json(renderer)),
         EnumItem(e) => ItemEnum::Enum(e.into_json(renderer)),
         VariantItem(v) => ItemEnum::Variant(v.into_json(renderer)),
-        FunctionItem(f) => ItemEnum::Function(from_function(f, true, header.unwrap(), renderer)),
+        FunctionItem(f) | TestItem(f) => {
+            ItemEnum::Function(from_function(f, true, header.unwrap(), renderer))
+        }
         ForeignFunctionItem(f, _) => {
             ItemEnum::Function(from_function(f, false, header.unwrap(), renderer))
         }
@@ -869,7 +871,7 @@ impl FromClean<ItemType> for ItemKind {
             Struct => ItemKind::Struct,
             Union => ItemKind::Union,
             Enum => ItemKind::Enum,
-            Function | TyMethod | Method => ItemKind::Function,
+            Function | Test | TyMethod | Method => ItemKind::Function,
             TypeAlias => ItemKind::TypeAlias,
             Static => ItemKind::Static,
             Constant => ItemKind::Constant,

src/librustdoc/lib.rs

@@ -685,6 +685,7 @@ fn opts() -> Vec<RustcOptGroup> {
             "[rust]",
         ),
         opt(Unstable, Flag, "", "html-no-source", "Disable HTML source code pages generation", ""),
+        opt(Unstable, FlagMulti, "", "document-tests", "Generate documentation for tests", ""),
     ]
 }
 

src/librustdoc/passes/propagate_stability.rs

@@ -46,6 +46,7 @@ impl DocFolder for StabilityPropagator<'_, '_> {
                     | ItemKind::UnionItem(..)
                     | ItemKind::EnumItem(..)
                     | ItemKind::FunctionItem(..)
+                    | ItemKind::TestItem(..)
                     | ItemKind::ModuleItem(..)
                     | ItemKind::TypeAliasItem(..)
                     | ItemKind::StaticItem(..)

src/librustdoc/passes/stripper.rs

@@ -57,6 +57,7 @@ impl DocFolder for Stripper<'_, '_> {
             | clean::EnumItem(..)
             | clean::TraitItem(..)
             | clean::FunctionItem(..)
+            | clean::TestItem(..)
             | clean::VariantItem(..)
             | clean::ForeignFunctionItem(..)
             | clean::ForeignStaticItem(..)

src/librustdoc/visit.rs

@@ -31,6 +31,7 @@ pub(crate) trait DocVisitor<'a>: Sized {
             ExternCrateItem { src: _ }
             | ImportItem(_)
             | FunctionItem(_)
+            | TestItem(_)
             | TypeAliasItem(_)
             | StaticItem(_)
             | ConstantItem(..)