Skip to content

Commit 8b898d1

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of rust-lang#133595 - GuillaumeGomez:missing_doc_code_examples, r=notriddle
Do not emit `missing_doc_code_examples` rustdoc lint on module and a few other items It doesn't make sense to expect modules to have code examples. Same goes for: * Trait aliases * Foreign items * Associated types and constants Should make the use of this lint a bit nicer. r? `@notriddle`
2 parents 9f7755e + b118d05 commit 8b898d1

13 files changed

+39
-64
lines changed

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

+4
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ It can be enabled using:
4747
#![deny(rustdoc::missing_doc_code_examples)]
4848
```
4949

50+
It is not emitted for items that cannot be instantiated/called such as fields, variants, modules,
51+
associated trait/impl items, impl blocks, statics and constants.
52+
It is also not emitted for foreign items, aliases, extern crates and imports.
53+
5054
## Extensions to the `#[doc]` attribute
5155

5256
These features operate by extending the `#[doc]` attribute, and thus can be caught by the compiler

‎src/librustdoc/passes/check_doc_test_visibility.rs

+9-2
Original file line numberDiff line numberDiff line change
@@ -60,15 +60,22 @@ pub(crate) fn should_have_doc_example(cx: &DocContext<'_>, item: &clean::Item) -
6060
item.kind,
6161
clean::StructFieldItem(_)
6262
| clean::VariantItem(_)
63-
| clean::AssocConstItem(..)
64-
| clean::AssocTypeItem(..)
6563
| clean::TypeAliasItem(_)
6664
| clean::StaticItem(_)
6765
| clean::ConstantItem(..)
6866
| clean::ExternCrateItem { .. }
6967
| clean::ImportItem(_)
7068
| clean::PrimitiveItem(_)
7169
| clean::KeywordItem
70+
| clean::ModuleItem(_)
71+
| clean::TraitAliasItem(_)
72+
| clean::ForeignFunctionItem(..)
73+
| clean::ForeignStaticItem(..)
74+
| clean::ForeignTypeItem
75+
| clean::AssocConstItem(..)
76+
| clean::AssocTypeItem(..)
77+
| clean::TyAssocConstItem(..)
78+
| clean::TyAssocTypeItem(..)
7279
// check for trait impl
7380
| clean::ImplItem(box clean::Impl { trait_: Some(_), .. })
7481
)

‎tests/rustdoc-ui/coverage/doc-examples-json.stdout

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{"$DIR/doc-examples-json.rs":{"total":3,"with_docs":2,"total_examples":2,"with_examples":1}}
1+
{"$DIR/doc-examples-json.rs":{"total":3,"with_docs":2,"total_examples":1,"with_examples":1}}

‎tests/rustdoc-ui/coverage/doc-examples.stdout

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
+-------------------------------------+------------+------------+------------+------------+
22
| File | Documented | Percentage | Examples | Percentage |
33
+-------------------------------------+------------+------------+------------+------------+
4-
| ...tdoc-ui/coverage/doc-examples.rs | 4 | 100.0% | 1 | 25.0% |
4+
| ...tdoc-ui/coverage/doc-examples.rs | 4 | 100.0% | 1 | 33.3% |
55
+-------------------------------------+------------+------------+------------+------------+
6-
| Total | 4 | 100.0% | 1 | 25.0% |
6+
| Total | 4 | 100.0% | 1 | 33.3% |
77
+-------------------------------------+------------+------------+------------+------------+

‎tests/rustdoc-ui/coverage/json.stdout

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{"$DIR/json.rs":{"total":17,"with_docs":12,"total_examples":15,"with_examples":6}}
1+
{"$DIR/json.rs":{"total":17,"with_docs":12,"total_examples":13,"with_examples":6}}

‎tests/rustdoc-ui/lints/check.rs

-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44

55
#![feature(rustdoc_missing_doc_code_examples)]
66
//~^ WARN
7-
//~^^ WARN
87

98
#![warn(missing_docs)]
109
#![warn(rustdoc::missing_doc_code_examples)]

‎tests/rustdoc-ui/lints/check.stderr

+9-19
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,20 @@ warning: missing documentation for the crate
44
LL | / #![feature(rustdoc_missing_doc_code_examples)]
55
LL | |
66
LL | |
7+
LL | | #![warn(missing_docs)]
78
... |
89
LL | |
910
LL | | pub fn foo() {}
1011
| |_______________^
1112
|
1213
note: the lint level is defined here
13-
--> $DIR/check.rs:9:9
14+
--> $DIR/check.rs:8:9
1415
|
1516
LL | #![warn(missing_docs)]
1617
| ^^^^^^^^^^^^
1718

1819
warning: missing documentation for a function
19-
--> $DIR/check.rs:13:1
20+
--> $DIR/check.rs:12:1
2021
|
2122
LL | pub fn foo() {}
2223
| ^^^^^^^^^^^^
@@ -26,34 +27,23 @@ warning: no documentation found for this crate's top-level module
2627
= help: The following guide may be of use:
2728
https://doc.rust-lang.org/$CHANNEL/rustdoc/how-to-write-documentation.html
2829
note: the lint level is defined here
29-
--> $DIR/check.rs:11:9
30+
--> $DIR/check.rs:10:9
3031
|
3132
LL | #![warn(rustdoc::all)]
3233
| ^^^^^^^^^^^^
3334
= note: `#[warn(rustdoc::missing_crate_level_docs)]` implied by `#[warn(rustdoc::all)]`
3435

3536
warning: missing code example in this documentation
36-
--> $DIR/check.rs:5:1
37+
--> $DIR/check.rs:12:1
3738
|
38-
LL | / #![feature(rustdoc_missing_doc_code_examples)]
39-
LL | |
40-
LL | |
41-
... |
42-
LL | |
43-
LL | | pub fn foo() {}
44-
| |_______________^
39+
LL | pub fn foo() {}
40+
| ^^^^^^^^^^^^^^^
4541
|
4642
note: the lint level is defined here
47-
--> $DIR/check.rs:10:9
43+
--> $DIR/check.rs:9:9
4844
|
4945
LL | #![warn(rustdoc::missing_doc_code_examples)]
5046
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5147

52-
warning: missing code example in this documentation
53-
--> $DIR/check.rs:13:1
54-
|
55-
LL | pub fn foo() {}
56-
| ^^^^^^^^^^^^^^^
57-
58-
warning: 5 warnings emitted
48+
warning: 4 warnings emitted
5949

‎tests/rustdoc-ui/lints/doc-without-codeblock.rs

+1-2
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
1-
#![feature(rustdoc_missing_doc_code_examples)] //~ ERROR missing code example in this documentation
1+
#![feature(rustdoc_missing_doc_code_examples)]
22
#![deny(rustdoc::missing_doc_code_examples)]
33

44
/// Some docs.
55
//~^ ERROR missing code example in this documentation
66
pub struct Foo;
77

88
/// And then, the princess died.
9-
//~^ ERROR missing code example in this documentation
109
pub mod foo {
1110
/// Or maybe not because she saved herself!
1211
//~^ ERROR missing code example in this documentation

‎tests/rustdoc-ui/lints/doc-without-codeblock.stderr

+4-22
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,20 @@
11
error: missing code example in this documentation
2-
--> $DIR/doc-without-codeblock.rs:1:1
2+
--> $DIR/doc-without-codeblock.rs:10:5
33
|
4-
LL | / #![feature(rustdoc_missing_doc_code_examples)]
5-
LL | | #![deny(rustdoc::missing_doc_code_examples)]
6-
LL | |
7-
LL | | /// Some docs.
8-
... |
9-
LL | | }
10-
LL | | }
11-
| |_^
4+
LL | /// Or maybe not because she saved herself!
5+
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
126
|
137
note: the lint level is defined here
148
--> $DIR/doc-without-codeblock.rs:2:9
159
|
1610
LL | #![deny(rustdoc::missing_doc_code_examples)]
1711
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1812

19-
error: missing code example in this documentation
20-
--> $DIR/doc-without-codeblock.rs:8:1
21-
|
22-
LL | /// And then, the princess died.
23-
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
24-
25-
error: missing code example in this documentation
26-
--> $DIR/doc-without-codeblock.rs:11:5
27-
|
28-
LL | /// Or maybe not because she saved herself!
29-
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
30-
3113
error: missing code example in this documentation
3214
--> $DIR/doc-without-codeblock.rs:4:1
3315
|
3416
LL | /// Some docs.
3517
| ^^^^^^^^^^^^^^
3618

37-
error: aborting due to 4 previous errors
19+
error: aborting due to 2 previous errors
3820

‎tests/rustdoc-ui/lints/lint-missing-doc-code-example.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ pub fn test() {
1717
}
1818

1919
#[allow(missing_docs)]
20-
pub mod module1 { //~ ERROR
20+
pub mod module1 {
2121
}
2222

2323
#[allow(rustdoc::missing_doc_code_examples)]

‎tests/rustdoc-ui/lints/lint-missing-doc-code-example.stderr

+4-10
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,15 @@
11
error: missing code example in this documentation
2-
--> $DIR/lint-missing-doc-code-example.rs:20:1
2+
--> $DIR/lint-missing-doc-code-example.rs:38:3
33
|
4-
LL | pub mod module1 {
5-
| ^^^^^^^^^^^^^^^
4+
LL | /// doc
5+
| ^^^^^^^
66
|
77
note: the lint level is defined here
88
--> $DIR/lint-missing-doc-code-example.rs:3:9
99
|
1010
LL | #![deny(rustdoc::missing_doc_code_examples)]
1111
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1212

13-
error: missing code example in this documentation
14-
--> $DIR/lint-missing-doc-code-example.rs:38:3
15-
|
16-
LL | /// doc
17-
| ^^^^^^^
18-
1913
error: missing code example in this documentation
2014
--> $DIR/lint-missing-doc-code-example.rs:50:1
2115
|
@@ -34,5 +28,5 @@ error: missing code example in this documentation
3428
LL | /// Doc
3529
| ^^^^^^^
3630

37-
error: aborting due to 5 previous errors
31+
error: aborting due to 4 previous errors
3832

‎tests/rustdoc-ui/show-coverage-json.stdout

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{"$DIR/show-coverage-json.rs":{"total":2,"with_docs":1,"total_examples":2,"with_examples":1}}
1+
{"$DIR/show-coverage-json.rs":{"total":2,"with_docs":1,"total_examples":1,"with_examples":1}}

‎tests/rustdoc-ui/show-coverage.stdout

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
+-------------------------------------+------------+------------+------------+------------+
22
| File | Documented | Percentage | Examples | Percentage |
33
+-------------------------------------+------------+------------+------------+------------+
4-
| ...ests/rustdoc-ui/show-coverage.rs | 1 | 50.0% | 1 | 50.0% |
4+
| ...ests/rustdoc-ui/show-coverage.rs | 1 | 50.0% | 1 | 100.0% |
55
+-------------------------------------+------------+------------+------------+------------+
6-
| Total | 1 | 50.0% | 1 | 50.0% |
6+
| Total | 1 | 50.0% | 1 | 100.0% |
77
+-------------------------------------+------------+------------+------------+------------+

0 commit comments

Comments
 (0)