Skip to content

Commit 441c835

Browse files
Dylan-DPCDylan-DPC
authored
Rollup merge of #75718 - GuillaumeGomez:coverage-ui-doc-examples-count, r=jyn514
Don't count variants/fields/consts/associated types in doc-coverage doc examples Fixes #75714. I think I'll need to update the equivalent lint too. Creating an issue for that! r? @jyn514
2 parents 6cb98e3 + adeedf5 commit 441c835

14 files changed

+196
-94
lines changed

Diff for: ‎src/doc/rustdoc/src/unstable-features.md

+33
Original file line numberDiff line numberDiff line change
@@ -467,3 +467,36 @@ $ rustdoc src/lib.rs -Z unstable-options --runtool valgrind
467467
```
468468

469469
Another use case would be to run a test inside an emulator, or through a Virtual Machine.
470+
471+
### `--show-coverage`: get statistics about code documentation coverage
472+
473+
This option allows you to get a nice overview over your code documentation coverage, including both
474+
doc-comments and code examples in the doc-comments. Example:
475+
476+
```bash
477+
$ rustdoc src/lib.rs -Z unstable-options --show-coverage
478+
+-------------------------------------+------------+------------+------------+------------+
479+
| File | Documented | Percentage | Examples | Percentage |
480+
+-------------------------------------+------------+------------+------------+------------+
481+
| lib.rs | 4 | 100.0% | 1 | 25.0% |
482+
+-------------------------------------+------------+------------+------------+------------+
483+
| Total | 4 | 100.0% | 1 | 25.0% |
484+
+-------------------------------------+------------+------------+------------+------------+
485+
```
486+
487+
You can also use this option with the `--output-format` one:
488+
489+
```bash
490+
$ rustdoc src/lib.rs -Z unstable-options --show-coverage --output-format json
491+
{"lib.rs":{"total":4,"with_docs":4,"total_examples":4,"with_examples":1}}
492+
```
493+
494+
Calculating code examples follows these rules:
495+
496+
1. These items aren't accounted by default:
497+
* struct/union field
498+
* enum variant
499+
* constant
500+
* static
501+
* typedef
502+
2. If one of the previously listed items has a code example, then it'll be counted.

Diff for: ‎src/librustdoc/passes/calculate_doc_coverage.rs

+52-35
Original file line numberDiff line numberDiff line change
@@ -27,20 +27,29 @@ fn calculate_doc_coverage(krate: clean::Crate, ctx: &DocContext<'_>) -> clean::C
2727
krate
2828
}
2929

30-
#[derive(Default, Copy, Clone, Serialize)]
30+
#[derive(Default, Copy, Clone, Serialize, Debug)]
3131
struct ItemCount {
3232
total: u64,
3333
with_docs: u64,
34+
total_examples: u64,
3435
with_examples: u64,
3536
}
3637

3738
impl ItemCount {
38-
fn count_item(&mut self, has_docs: bool, has_doc_example: bool) {
39+
fn count_item(
40+
&mut self,
41+
has_docs: bool,
42+
has_doc_example: bool,
43+
should_have_doc_examples: bool,
44+
) {
3945
self.total += 1;
4046

4147
if has_docs {
4248
self.with_docs += 1;
4349
}
50+
if should_have_doc_examples || has_doc_example {
51+
self.total_examples += 1;
52+
}
4453
if has_doc_example {
4554
self.with_examples += 1;
4655
}
@@ -55,8 +64,8 @@ impl ItemCount {
5564
}
5665

5766
fn examples_percentage(&self) -> Option<f64> {
58-
if self.total > 0 {
59-
Some((self.with_examples as f64 * 100.0) / self.total as f64)
67+
if self.total_examples > 0 {
68+
Some((self.with_examples as f64 * 100.0) / self.total_examples as f64)
6069
} else {
6170
None
6271
}
@@ -70,6 +79,7 @@ impl ops::Sub for ItemCount {
7079
ItemCount {
7180
total: self.total - rhs.total,
7281
with_docs: self.with_docs - rhs.with_docs,
82+
total_examples: self.total_examples - rhs.total_examples,
7383
with_examples: self.with_examples - rhs.with_examples,
7484
}
7585
}
@@ -79,6 +89,7 @@ impl ops::AddAssign for ItemCount {
7989
fn add_assign(&mut self, rhs: Self) {
8090
self.total += rhs.total;
8191
self.with_docs += rhs.with_docs;
92+
self.total_examples += rhs.total_examples;
8293
self.with_examples += rhs.with_examples;
8394
}
8495
}
@@ -121,7 +132,7 @@ impl CoverageCalculator {
121132
let mut total = ItemCount::default();
122133

123134
fn print_table_line() {
124-
println!("+-{0:->35}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", "");
135+
println!("+-{0:->35}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", "");
125136
}
126137

127138
fn print_table_record(
@@ -131,32 +142,25 @@ impl CoverageCalculator {
131142
examples_percentage: f64,
132143
) {
133144
println!(
134-
"| {:<35} | {:>10} | {:>10} | {:>9.1}% | {:>10} | {:>9.1}% |",
135-
name,
136-
count.with_docs,
137-
count.total,
138-
percentage,
139-
count.with_examples,
140-
examples_percentage,
145+
"| {:<35} | {:>10} | {:>9.1}% | {:>10} | {:>9.1}% |",
146+
name, count.with_docs, percentage, count.with_examples, examples_percentage,
141147
);
142148
}
143149

144150
print_table_line();
145151
println!(
146-
"| {:<35} | {:>10} | {:>10} | {:>10} | {:>10} | {:>10} |",
147-
"File", "Documented", "Total", "Percentage", "Examples", "Percentage",
152+
"| {:<35} | {:>10} | {:>10} | {:>10} | {:>10} |",
153+
"File", "Documented", "Percentage", "Examples", "Percentage",
148154
);
149155
print_table_line();
150156

151157
for (file, &count) in &self.items {
152-
if let (Some(percentage), Some(examples_percentage)) =
153-
(count.percentage(), count.examples_percentage())
154-
{
158+
if let Some(percentage) = count.percentage() {
155159
print_table_record(
156160
&limit_filename_len(file.to_string()),
157161
count,
158162
percentage,
159-
examples_percentage,
163+
count.examples_percentage().unwrap_or(0.),
160164
);
161165

162166
total += count;
@@ -176,19 +180,6 @@ impl CoverageCalculator {
176180

177181
impl fold::DocFolder for CoverageCalculator {
178182
fn fold_item(&mut self, i: clean::Item) -> Option<clean::Item> {
179-
let has_docs = !i.attrs.doc_strings.is_empty();
180-
let mut tests = Tests { found_tests: 0 };
181-
182-
find_testable_code(
183-
&i.attrs.doc_strings.iter().map(|d| d.as_str()).collect::<Vec<_>>().join("\n"),
184-
&mut tests,
185-
ErrorCodes::No,
186-
false,
187-
None,
188-
);
189-
190-
let has_doc_example = tests.found_tests != 0;
191-
192183
match i.inner {
193184
_ if !i.def_id.is_local() => {
194185
// non-local items are skipped because they can be out of the users control,
@@ -237,11 +228,37 @@ impl fold::DocFolder for CoverageCalculator {
237228
}
238229
}
239230
_ => {
231+
let has_docs = !i.attrs.doc_strings.is_empty();
232+
let mut tests = Tests { found_tests: 0 };
233+
234+
let should_have_doc_examples = !matches!(i.inner,
235+
clean::StructFieldItem(_)
236+
| clean::VariantItem(_)
237+
| clean::AssocConstItem(_, _)
238+
| clean::AssocTypeItem(_, _)
239+
| clean::TypedefItem(_, _)
240+
| clean::StaticItem(_)
241+
| clean::ConstantItem(_)
242+
| clean::ExternCrateItem(_, _)
243+
| clean::ImportItem(_)
244+
| clean::PrimitiveItem(_)
245+
| clean::KeywordItem(_)
246+
);
247+
find_testable_code(
248+
&i.attrs.doc_strings.iter().map(|d| d.as_str()).collect::<Vec<_>>().join("\n"),
249+
&mut tests,
250+
ErrorCodes::No,
251+
false,
252+
None,
253+
);
254+
255+
let has_doc_example = tests.found_tests != 0;
240256
debug!("counting {:?} {:?} in {}", i.type_(), i.name, i.source.filename);
241-
self.items
242-
.entry(i.source.filename.clone())
243-
.or_default()
244-
.count_item(has_docs, has_doc_example);
257+
self.items.entry(i.source.filename.clone()).or_default().count_item(
258+
has_docs,
259+
has_doc_example,
260+
should_have_doc_examples,
261+
);
245262
}
246263
}
247264

Diff for: ‎src/test/rustdoc-ui/coverage/basic.stdout

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
+-------------------------------------+------------+------------+------------+------------+------------+
2-
| File | Documented | Total | Percentage | Examples | Percentage |
3-
+-------------------------------------+------------+------------+------------+------------+------------+
4-
| ...est/rustdoc-ui/coverage/basic.rs | 7 | 14 | 50.0% | 0 | 0.0% |
5-
+-------------------------------------+------------+------------+------------+------------+------------+
6-
| Total | 7 | 14 | 50.0% | 0 | 0.0% |
7-
+-------------------------------------+------------+------------+------------+------------+------------+
1+
+-------------------------------------+------------+------------+------------+------------+
2+
| File | Documented | Percentage | Examples | Percentage |
3+
+-------------------------------------+------------+------------+------------+------------+
4+
| ...est/rustdoc-ui/coverage/basic.rs | 7 | 50.0% | 0 | 0.0% |
5+
+-------------------------------------+------------+------------+------------+------------+
6+
| Total | 7 | 50.0% | 0 | 0.0% |
7+
+-------------------------------------+------------+------------+------------+------------+

Diff for: ‎src/test/rustdoc-ui/coverage/doc-examples-json.rs

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// check-pass
2+
// compile-flags:-Z unstable-options --output-format json --show-coverage
3+
4+
// This check ensures that only one doc example is counted since they're "optional" on
5+
// certain items.
6+
7+
/// ```
8+
/// let x = 12;
9+
/// ```
10+
pub const Foo: u32 = 0;
11+
12+
/// doc
13+
pub const Bar: u32 = 0;

Diff for: ‎src/test/rustdoc-ui/coverage/doc-examples-json.stdout

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

Diff for: ‎src/test/rustdoc-ui/coverage/doc-examples.stdout

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
+-------------------------------------+------------+------------+------------+------------+------------+
2-
| File | Documented | Total | Percentage | Examples | Percentage |
3-
+-------------------------------------+------------+------------+------------+------------+------------+
4-
| ...tdoc-ui/coverage/doc-examples.rs | 4 | 4 | 100.0% | 2 | 50.0% |
5-
+-------------------------------------+------------+------------+------------+------------+------------+
6-
| Total | 4 | 4 | 100.0% | 2 | 50.0% |
7-
+-------------------------------------+------------+------------+------------+------------+------------+
1+
+-------------------------------------+------------+------------+------------+------------+
2+
| File | Documented | Percentage | Examples | Percentage |
3+
+-------------------------------------+------------+------------+------------+------------+
4+
| ...tdoc-ui/coverage/doc-examples.rs | 4 | 100.0% | 2 | 50.0% |
5+
+-------------------------------------+------------+------------+------------+------------+
6+
| Total | 4 | 100.0% | 2 | 50.0% |
7+
+-------------------------------------+------------+------------+------------+------------+

Diff for: ‎src/test/rustdoc-ui/coverage/empty.stdout

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
+-------------------------------------+------------+------------+------------+------------+------------+
2-
| File | Documented | Total | Percentage | Examples | Percentage |
3-
+-------------------------------------+------------+------------+------------+------------+------------+
4-
| ...est/rustdoc-ui/coverage/empty.rs | 0 | 1 | 0.0% | 0 | 0.0% |
5-
+-------------------------------------+------------+------------+------------+------------+------------+
6-
| Total | 0 | 1 | 0.0% | 0 | 0.0% |
7-
+-------------------------------------+------------+------------+------------+------------+------------+
1+
+-------------------------------------+------------+------------+------------+------------+
2+
| File | Documented | Percentage | Examples | Percentage |
3+
+-------------------------------------+------------+------------+------------+------------+
4+
| ...est/rustdoc-ui/coverage/empty.rs | 0 | 0.0% | 0 | 0.0% |
5+
+-------------------------------------+------------+------------+------------+------------+
6+
| Total | 0 | 0.0% | 0 | 0.0% |
7+
+-------------------------------------+------------+------------+------------+------------+

Diff for: ‎src/test/rustdoc-ui/coverage/enums.stdout

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
+-------------------------------------+------------+------------+------------+------------+------------+
2-
| File | Documented | Total | Percentage | Examples | Percentage |
3-
+-------------------------------------+------------+------------+------------+------------+------------+
4-
| ...est/rustdoc-ui/coverage/enums.rs | 6 | 8 | 75.0% | 0 | 0.0% |
5-
+-------------------------------------+------------+------------+------------+------------+------------+
6-
| Total | 6 | 8 | 75.0% | 0 | 0.0% |
7-
+-------------------------------------+------------+------------+------------+------------+------------+
1+
+-------------------------------------+------------+------------+------------+------------+
2+
| File | Documented | Percentage | Examples | Percentage |
3+
+-------------------------------------+------------+------------+------------+------------+
4+
| ...est/rustdoc-ui/coverage/enums.rs | 6 | 75.0% | 0 | 0.0% |
5+
+-------------------------------------+------------+------------+------------+------------+
6+
| Total | 6 | 75.0% | 0 | 0.0% |
7+
+-------------------------------------+------------+------------+------------+------------+

Diff for: ‎src/test/rustdoc-ui/coverage/exotic.stdout

+8-8
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
+-------------------------------------+------------+------------+------------+------------+------------+
2-
| File | Documented | Total | Percentage | Examples | Percentage |
3-
+-------------------------------------+------------+------------+------------+------------+------------+
4-
| ...st/rustdoc-ui/coverage/exotic.rs | 1 | 1 | 100.0% | 0 | 0.0% |
5-
| <anon> | 2 | 2 | 100.0% | 0 | 0.0% |
6-
+-------------------------------------+------------+------------+------------+------------+------------+
7-
| Total | 3 | 3 | 100.0% | 0 | 0.0% |
8-
+-------------------------------------+------------+------------+------------+------------+------------+
1+
+-------------------------------------+------------+------------+------------+------------+
2+
| File | Documented | Percentage | Examples | Percentage |
3+
+-------------------------------------+------------+------------+------------+------------+
4+
| ...st/rustdoc-ui/coverage/exotic.rs | 1 | 100.0% | 0 | 0.0% |
5+
| <anon> | 2 | 100.0% | 0 | 0.0% |
6+
+-------------------------------------+------------+------------+------------+------------+
7+
| Total | 3 | 100.0% | 0 | 0.0% |
8+
+-------------------------------------+------------+------------+------------+------------+

Diff for: ‎src/test/rustdoc-ui/coverage/json.rs

+39-1
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,54 @@ pub mod foo {
1212
pub struct X;
1313

1414
/// Bar
15+
///
16+
/// ```
17+
/// let x = 12;
18+
/// ```
1519
pub mod bar {
1620
/// bar
1721
pub struct Bar;
1822
/// X
19-
pub enum X { Y }
23+
pub enum X {
24+
/// ```
25+
/// let x = "should be ignored!";
26+
/// ```
27+
Y
28+
}
2029
}
2130

2231
/// yolo
32+
///
33+
/// ```text
34+
/// should not be counted as a code example!
35+
/// ```
2336
pub enum Yolo { X }
2437

38+
impl Yolo {
39+
/// ```
40+
/// let x = "should be ignored!";
41+
/// ```
42+
pub const Const: u32 = 0;
43+
}
44+
2545
pub struct Xo<T: Clone> {
46+
/// ```
47+
/// let x = "should be ignored!";
48+
/// ```
2649
x: T,
2750
}
51+
52+
/// ```
53+
/// let x = "should be ignored!";
54+
/// ```
55+
pub static StaticFoo: u32 = 0;
56+
57+
/// ```
58+
/// let x = "should be ignored!";
59+
/// ```
60+
pub const ConstFoo: u32 = 0;
61+
62+
/// ```
63+
/// let x = "should be ignored!";
64+
/// ```
65+
pub type TypeFoo = u32;

Diff for: ‎src/test/rustdoc-ui/coverage/json.stdout

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

Diff for: ‎src/test/rustdoc-ui/coverage/private.stdout

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
+-------------------------------------+------------+------------+------------+------------+------------+
2-
| File | Documented | Total | Percentage | Examples | Percentage |
3-
+-------------------------------------+------------+------------+------------+------------+------------+
4-
| ...t/rustdoc-ui/coverage/private.rs | 4 | 7 | 57.1% | 0 | 0.0% |
5-
+-------------------------------------+------------+------------+------------+------------+------------+
6-
| Total | 4 | 7 | 57.1% | 0 | 0.0% |
7-
+-------------------------------------+------------+------------+------------+------------+------------+
1+
+-------------------------------------+------------+------------+------------+------------+
2+
| File | Documented | Percentage | Examples | Percentage |
3+
+-------------------------------------+------------+------------+------------+------------+
4+
| ...t/rustdoc-ui/coverage/private.rs | 4 | 57.1% | 0 | 0.0% |
5+
+-------------------------------------+------------+------------+------------+------------+
6+
| Total | 4 | 57.1% | 0 | 0.0% |
7+
+-------------------------------------+------------+------------+------------+------------+

Diff for: ‎src/test/rustdoc-ui/coverage/statics-consts.stdout

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
+-------------------------------------+------------+------------+------------+------------+------------+
2-
| File | Documented | Total | Percentage | Examples | Percentage |
3-
+-------------------------------------+------------+------------+------------+------------+------------+
4-
| ...oc-ui/coverage/statics-consts.rs | 6 | 7 | 85.7% | 0 | 0.0% |
5-
+-------------------------------------+------------+------------+------------+------------+------------+
6-
| Total | 6 | 7 | 85.7% | 0 | 0.0% |
7-
+-------------------------------------+------------+------------+------------+------------+------------+
1+
+-------------------------------------+------------+------------+------------+------------+
2+
| File | Documented | Percentage | Examples | Percentage |
3+
+-------------------------------------+------------+------------+------------+------------+
4+
| ...oc-ui/coverage/statics-consts.rs | 6 | 85.7% | 0 | 0.0% |
5+
+-------------------------------------+------------+------------+------------+------------+
6+
| Total | 6 | 85.7% | 0 | 0.0% |
7+
+-------------------------------------+------------+------------+------------+------------+

0 commit comments

Comments
 (0)