Skip to content

Commit 98f7d88

Browse files
JohnTitorJohnTitor
authored
Rollup merge of #75665 - GuillaumeGomez:doc-examples-coverage, r=jyn514
Add doc examples coverage r? @jyn514
2 parents e6fe523 + f957bae commit 98f7d88

13 files changed

+173
-77
lines changed

‎src/librustdoc/html/render/cache.rs

+4-2
Original file line numberDiff line numberDiff line change
@@ -200,10 +200,12 @@ fn get_index_type_name(clean_type: &clean::Type, accept_generic: bool) -> Option
200200
match *clean_type {
201201
clean::ResolvedPath { ref path, .. } => {
202202
let segments = &path.segments;
203-
let path_segment = segments.iter().last().unwrap_or_else(|| panic!(
203+
let path_segment = segments.iter().last().unwrap_or_else(|| {
204+
panic!(
204205
"get_index_type_name(clean_type: {:?}, accept_generic: {:?}) had length zero path",
205206
clean_type, accept_generic
206-
));
207+
)
208+
});
207209
Some(path_segment.name.clone())
208210
}
209211
clean::Generic(ref s) if accept_generic => Some(s.clone()),

‎src/librustdoc/passes/calculate_doc_coverage.rs

+67-13
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@ use crate::clean;
22
use crate::config::OutputFormat;
33
use crate::core::DocContext;
44
use crate::fold::{self, DocFolder};
5+
use crate::html::markdown::{find_testable_code, ErrorCodes};
6+
use crate::passes::doc_test_lints::Tests;
57
use crate::passes::Pass;
6-
78
use rustc_span::symbol::sym;
89
use rustc_span::FileName;
910
use serde::Serialize;
@@ -30,15 +31,19 @@ fn calculate_doc_coverage(krate: clean::Crate, ctx: &DocContext<'_>) -> clean::C
3031
struct ItemCount {
3132
total: u64,
3233
with_docs: u64,
34+
with_examples: u64,
3335
}
3436

3537
impl ItemCount {
36-
fn count_item(&mut self, has_docs: bool) {
38+
fn count_item(&mut self, has_docs: bool, has_doc_example: bool) {
3739
self.total += 1;
3840

3941
if has_docs {
4042
self.with_docs += 1;
4143
}
44+
if has_doc_example {
45+
self.with_examples += 1;
46+
}
4247
}
4348

4449
fn percentage(&self) -> Option<f64> {
@@ -48,20 +53,33 @@ impl ItemCount {
4853
None
4954
}
5055
}
56+
57+
fn examples_percentage(&self) -> Option<f64> {
58+
if self.total > 0 {
59+
Some((self.with_examples as f64 * 100.0) / self.total as f64)
60+
} else {
61+
None
62+
}
63+
}
5164
}
5265

5366
impl ops::Sub for ItemCount {
5467
type Output = Self;
5568

5669
fn sub(self, rhs: Self) -> Self {
57-
ItemCount { total: self.total - rhs.total, with_docs: self.with_docs - rhs.with_docs }
70+
ItemCount {
71+
total: self.total - rhs.total,
72+
with_docs: self.with_docs - rhs.with_docs,
73+
with_examples: self.with_examples - rhs.with_examples,
74+
}
5875
}
5976
}
6077

6178
impl ops::AddAssign for ItemCount {
6279
fn add_assign(&mut self, rhs: Self) {
6380
self.total += rhs.total;
6481
self.with_docs += rhs.with_docs;
82+
self.with_examples += rhs.with_examples;
6583
}
6684
}
6785

@@ -103,40 +121,73 @@ impl CoverageCalculator {
103121
let mut total = ItemCount::default();
104122

105123
fn print_table_line() {
106-
println!("+-{0:->35}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", "");
124+
println!("+-{0:->35}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", "");
107125
}
108126

109-
fn print_table_record(name: &str, count: ItemCount, percentage: f64) {
127+
fn print_table_record(
128+
name: &str,
129+
count: ItemCount,
130+
percentage: f64,
131+
examples_percentage: f64,
132+
) {
110133
println!(
111-
"| {:<35} | {:>10} | {:>10} | {:>9.1}% |",
112-
name, count.with_docs, count.total, percentage
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,
113141
);
114142
}
115143

116144
print_table_line();
117145
println!(
118-
"| {:<35} | {:>10} | {:>10} | {:>10} |",
119-
"File", "Documented", "Total", "Percentage"
146+
"| {:<35} | {:>10} | {:>10} | {:>10} | {:>10} | {:>10} |",
147+
"File", "Documented", "Total", "Percentage", "Examples", "Percentage",
120148
);
121149
print_table_line();
122150

123151
for (file, &count) in &self.items {
124-
if let Some(percentage) = count.percentage() {
125-
print_table_record(&limit_filename_len(file.to_string()), count, percentage);
152+
if let (Some(percentage), Some(examples_percentage)) =
153+
(count.percentage(), count.examples_percentage())
154+
{
155+
print_table_record(
156+
&limit_filename_len(file.to_string()),
157+
count,
158+
percentage,
159+
examples_percentage,
160+
);
126161

127162
total += count;
128163
}
129164
}
130165

131166
print_table_line();
132-
print_table_record("Total", total, total.percentage().unwrap_or(0.0));
167+
print_table_record(
168+
"Total",
169+
total,
170+
total.percentage().unwrap_or(0.0),
171+
total.examples_percentage().unwrap_or(0.0),
172+
);
133173
print_table_line();
134174
}
135175
}
136176

137177
impl fold::DocFolder for CoverageCalculator {
138178
fn fold_item(&mut self, i: clean::Item) -> Option<clean::Item> {
139179
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;
140191

141192
match i.inner {
142193
_ if !i.def_id.is_local() => {
@@ -187,7 +238,10 @@ impl fold::DocFolder for CoverageCalculator {
187238
}
188239
_ => {
189240
debug!("counting {:?} {:?} in {}", i.type_(), i.name, i.source.filename);
190-
self.items.entry(i.source.filename.clone()).or_default().count_item(has_docs);
241+
self.items
242+
.entry(i.source.filename.clone())
243+
.or_default()
244+
.count_item(has_docs, has_doc_example);
191245
}
192246
}
193247

‎src/librustdoc/passes/doc_test_lints.rs

+17-11
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,22 @@ impl<'a, 'tcx> DocFolder for PrivateItemDocTestLinter<'a, 'tcx> {
4343
}
4444
}
4545

46+
pub(crate) struct Tests {
47+
pub(crate) found_tests: usize,
48+
}
49+
50+
impl Tests {
51+
pub(crate) fn new() -> Tests {
52+
Tests { found_tests: 0 }
53+
}
54+
}
55+
56+
impl crate::test::Tester for Tests {
57+
fn add_test(&mut self, _: String, _: LangString, _: usize) {
58+
self.found_tests += 1;
59+
}
60+
}
61+
4662
pub fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
4763
let hir_id = match cx.as_local_hir_id(item.def_id) {
4864
Some(hir_id) => hir_id,
@@ -52,17 +68,7 @@ pub fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
5268
}
5369
};
5470

55-
struct Tests {
56-
found_tests: usize,
57-
}
58-
59-
impl crate::test::Tester for Tests {
60-
fn add_test(&mut self, _: String, _: LangString, _: usize) {
61-
self.found_tests += 1;
62-
}
63-
}
64-
65-
let mut tests = Tests { found_tests: 0 };
71+
let mut tests = Tests::new();
6672

6773
find_testable_code(&dox, &mut tests, ErrorCodes::No, false, None);
6874

‎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 |
3-
+-------------------------------------+------------+------------+------------+
4-
| ...est/rustdoc-ui/coverage/basic.rs | 7 | 14 | 50.0% |
5-
+-------------------------------------+------------+------------+------------+
6-
| Total | 7 | 14 | 50.0% |
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+
+-------------------------------------+------------+------------+------------+------------+------------+

‎src/test/rustdoc-ui/coverage/doc-examples.rs

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// compile-flags:-Z unstable-options --show-coverage
2+
// check-pass
3+
4+
//! This test ensure that only rust code examples are counted.
5+
6+
/// Doc
7+
///
8+
/// ```
9+
/// let x = 2;
10+
/// ```
11+
pub struct Foo;
12+
13+
/// Doc
14+
///
15+
/// ```text
16+
/// yolo
17+
/// ```
18+
pub trait Bar {}
19+
20+
/// Doc
21+
///
22+
/// ```ignore (just for the sake of this test)
23+
/// let x = 2;
24+
/// ```
25+
pub fn foo<T: Bar, D: ::std::fmt::Debug>(a: Foo, b: u32, c: T, d: D) -> u32 {
26+
0
27+
}

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

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +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+
+-------------------------------------+------------+------------+------------+------------+------------+

‎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 |
3-
+-------------------------------------+------------+------------+------------+
4-
| ...est/rustdoc-ui/coverage/empty.rs | 0 | 1 | 0.0% |
5-
+-------------------------------------+------------+------------+------------+
6-
| Total | 0 | 1 | 0.0% |
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+
+-------------------------------------+------------+------------+------------+------------+------------+

‎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 |
3-
+-------------------------------------+------------+------------+------------+
4-
| ...est/rustdoc-ui/coverage/enums.rs | 6 | 8 | 75.0% |
5-
+-------------------------------------+------------+------------+------------+
6-
| Total | 6 | 8 | 75.0% |
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+
+-------------------------------------+------------+------------+------------+------------+------------+

‎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 |
3-
+-------------------------------------+------------+------------+------------+
4-
| ...st/rustdoc-ui/coverage/exotic.rs | 1 | 1 | 100.0% |
5-
| <anon> | 2 | 2 | 100.0% |
6-
+-------------------------------------+------------+------------+------------+
7-
| Total | 3 | 3 | 100.0% |
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+
+-------------------------------------+------------+------------+------------+------------+------------+

‎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}}
1+
{"$DIR/json.rs":{"total":13,"with_docs":7,"with_examples":0}}

‎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 |
3-
+-------------------------------------+------------+------------+------------+
4-
| ...t/rustdoc-ui/coverage/private.rs | 4 | 7 | 57.1% |
5-
+-------------------------------------+------------+------------+------------+
6-
| Total | 4 | 7 | 57.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+
+-------------------------------------+------------+------------+------------+------------+------------+

‎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 |
3-
+-------------------------------------+------------+------------+------------+
4-
| ...oc-ui/coverage/statics-consts.rs | 6 | 7 | 85.7% |
5-
+-------------------------------------+------------+------------+------------+
6-
| Total | 6 | 7 | 85.7% |
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+
+-------------------------------------+------------+------------+------------+------------+------------+

‎src/test/rustdoc-ui/coverage/traits.stdout

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

0 commit comments

Comments
 (0)