Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 4f4be34

Browse files
ifxfrancoislucagladiator
authored andcommitted
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.
1 parent 259fdb5 commit 4f4be34

File tree

20 files changed

+129
-15
lines changed

20 files changed

+129
-15
lines changed

‎compiler/rustc_span/src/symbol.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -360,6 +360,7 @@ symbols! {
360360
SyncUnsafeCell,
361361
T,
362362
Target,
363+
TestDescAndFn,
363364
ToOwned,
364365
ToString,
365366
TokenStream,

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -830,3 +830,34 @@ will be split as follows:
830830
"you today?",
831831
]
832832
```
833+
834+
### `--document-tests`: show test items
835+
836+
Using this flag looks like this:
837+
838+
```bash
839+
$ rustdoc src/lib.rs -Z unstable-options --cfg test --document-private-items --document-tests
840+
```
841+
842+
By default, `rustdoc` does not document test items.
843+
844+
```rust
845+
/// by default this test function would not be documented
846+
#[test]
847+
fn test_in_module() {
848+
assert_eq!(2, 1 + 1);
849+
}
850+
/// by default this test module would not be documented
851+
#[cfg(test)]
852+
mod tests {
853+
/// by default this test function would not be documented
854+
#[test]
855+
fn test_in_a_test_module() {
856+
assert_eq!(2, 1 + 1);
857+
}
858+
}
859+
```
860+
861+
Note:
862+
* `--cfg test` must be set because tests are guarded by #[cfg(test)].
863+
* `--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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1048,7 +1048,11 @@ fn clean_fn_or_proc_macro<'tcx>(
10481048
None => {
10491049
let mut func = clean_function(cx, sig, generics, FunctionArgs::Body(body_id));
10501050
clean_fn_decl_legacy_const_generics(&mut func, attrs);
1051-
FunctionItem(func)
1051+
if cx.cache.document_tests && cx.cache.tests.contains(&item.owner_id.to_def_id()) {
1052+
TestItem(func)
1053+
} else {
1054+
FunctionItem(func)
1055+
}
10521056
}
10531057
}
10541058
}

‎src/librustdoc/clean/types.rs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -697,7 +697,8 @@ impl Item {
697697
}
698698
ItemKind::FunctionItem(_)
699699
| ItemKind::MethodItem(_, _)
700-
| ItemKind::RequiredMethodItem(_) => {
700+
| ItemKind::RequiredMethodItem(_)
701+
| ItemKind::TestItem(_) => {
701702
let def_id = self.def_id().unwrap();
702703
build_fn_header(def_id, tcx, tcx.asyncness(def_id))
703704
}
@@ -874,6 +875,7 @@ pub(crate) enum ItemKind {
874875
UnionItem(Union),
875876
EnumItem(Enum),
876877
FunctionItem(Box<Function>),
878+
TestItem(Box<Function>),
877879
ModuleItem(Module),
878880
TypeAliasItem(Box<TypeAlias>),
879881
StaticItem(Static),
@@ -934,6 +936,7 @@ impl ItemKind {
934936
ExternCrateItem { .. }
935937
| ImportItem(_)
936938
| FunctionItem(_)
939+
| TestItem(_)
937940
| TypeAliasItem(_)
938941
| StaticItem(_)
939942
| ConstantItem(_)

‎src/librustdoc/clean/types/tests.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ fn should_not_trim() {
7171
fn is_same_generic() {
7272
use crate::clean::types::{PrimitiveType, Type};
7373
use crate::formats::cache::Cache;
74-
let cache = Cache::new(false, false);
74+
let cache = Cache::new(false, false,false);
7575
let generic = Type::Generic(rustc_span::symbol::sym::Any);
7676
let unit = Type::Primitive(PrimitiveType::Unit);
7777
assert!(!generic.is_doc_subtype_of(&unit, &cache));

‎src/librustdoc/config.rs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,8 @@ pub(crate) struct RenderOptions {
283283
pub(crate) document_private: bool,
284284
/// Document items that have `doc(hidden)`.
285285
pub(crate) document_hidden: bool,
286+
/// Document tests.
287+
pub(crate) document_tests: bool,
286288
/// If `true`, generate a JSON file in the crate folder instead of HTML redirection files.
287289
pub(crate) generate_redirect_map: bool,
288290
/// Show the memory layout of types in the docs.
@@ -806,6 +808,7 @@ impl Options {
806808
}
807809

808810
let scrape_examples_options = ScrapeExamplesOptions::new(matches, dcx);
811+
let document_tests = matches.opt_present("document-tests");
809812
let with_examples = matches.opt_strs("with-examples");
810813
let call_locations = crate::scrape_examples::load_call_locations(with_examples, dcx);
811814
let doctest_compilation_args = matches.opt_strs("doctest-compilation-args");
@@ -880,6 +883,7 @@ impl Options {
880883
markdown_playground_url,
881884
document_private,
882885
document_hidden,
886+
document_tests,
883887
generate_redirect_map,
884888
show_type_layout,
885889
unstable_features,

‎src/librustdoc/core.rs

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -250,7 +250,8 @@ pub(crate) fn create_config(
250250
} else {
251251
ResolveDocLinks::Exported
252252
};
253-
let test = scrape_examples_options.map(|opts| opts.scrape_tests).unwrap_or(false);
253+
let test = scrape_examples_options.map(|opts| opts.scrape_tests).unwrap_or(false)
254+
|| (cfgs.iter().any(|cfg| cfg == "test") && render_options.document_tests);
254255
// plays with error output here!
255256
let sessopts = config::Options {
256257
sysroot,
@@ -369,7 +370,11 @@ pub(crate) fn run_global_ctxt(
369370
impl_trait_bounds: Default::default(),
370371
generated_synthetics: Default::default(),
371372
auto_traits,
372-
cache: Cache::new(render_options.document_private, render_options.document_hidden),
373+
cache: Cache::new(
374+
render_options.document_private,
375+
render_options.document_hidden,
376+
render_options.document_tests,
377+
),
373378
inlined: FxHashSet::default(),
374379
output_format,
375380
render_options,

‎src/librustdoc/fold.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ pub(crate) trait DocFolder: Sized {
7979
ExternCrateItem { src: _ }
8080
| ImportItem(_)
8181
| FunctionItem(_)
82+
| TestItem(_)
8283
| StaticItem(_)
8384
| ConstantItem(..)
8485
| TraitAliasItem(_)

‎src/librustdoc/formats/cache.rs

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,11 @@ pub(crate) struct Cache {
9292
/// Whether to document hidden items.
9393
/// This is stored in `Cache` so it doesn't need to be passed through all rustdoc functions.
9494
pub(crate) document_hidden: bool,
95+
/// Whether to document tests.
96+
/// This is stored in `Cache` so it doesn't need to be passed through all rustdoc functions.
97+
pub(crate) document_tests: bool,
98+
/// DefIds of all functions which are tests.
99+
pub(crate) tests: FxHashSet<DefId>,
95100

96101
/// Crates marked with [`#[doc(masked)]`][doc_masked].
97102
///
@@ -144,8 +149,8 @@ struct CacheBuilder<'a, 'tcx> {
144149
}
145150

146151
impl Cache {
147-
pub(crate) fn new(document_private: bool, document_hidden: bool) -> Self {
148-
Cache { document_private, document_hidden, ..Cache::default() }
152+
pub(crate) fn new(document_private: bool, document_hidden: bool,document_tests:bool) -> Self {
153+
Cache { document_private, document_hidden, document_tests,..Cache::default() }
149154
}
150155

151156
/// Populates the `Cache` with more data. The returned `Crate` will be missing some data that was
@@ -302,6 +307,7 @@ impl DocFolder for CacheBuilder<'_, '_> {
302307
| clean::TraitItem(..)
303308
| clean::TraitAliasItem(..)
304309
| clean::FunctionItem(..)
310+
| clean::TestItem(..)
305311
| clean::ModuleItem(..)
306312
| clean::ForeignFunctionItem(..)
307313
| clean::ForeignStaticItem(..)

‎src/librustdoc/formats/item_type.rs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ pub(crate) enum ItemType {
5757
TraitAlias = 25,
5858
// This number is reserved for use in JavaScript
5959
// Generic = 26,
60+
Test = 27,
6061
}
6162

6263
impl Serialize for ItemType {
@@ -83,6 +84,7 @@ impl<'a> From<&'a clean::Item> for ItemType {
8384
clean::UnionItem(..) => ItemType::Union,
8485
clean::EnumItem(..) => ItemType::Enum,
8586
clean::FunctionItem(..) => ItemType::Function,
87+
clean::TestItem(..) => ItemType::Test,
8688
clean::TypeAliasItem(..) => ItemType::TypeAlias,
8789
clean::StaticItem(..) => ItemType::Static,
8890
clean::ConstantItem(..) => ItemType::Constant,
@@ -178,6 +180,7 @@ impl ItemType {
178180
ItemType::Union => "union",
179181
ItemType::Enum => "enum",
180182
ItemType::Function => "fn",
183+
ItemType::Test => "test",
181184
ItemType::TypeAlias => "type",
182185
ItemType::Static => "static",
183186
ItemType::Trait => "trait",

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /