Rollup merge of #75665 - GuillaumeGomez:doc-examples-coverage, r=jyn514

Add doc examples coverage

r? @jyn514

src/librustdoc/html/render/cache.rs

@@ -200,10 +200,12 @@ fn get_index_type_name(clean_type: &clean::Type, accept_generic: bool) -> Option
     match *clean_type {
         clean::ResolvedPath { ref path, .. } => {
             let segments = &path.segments;
-            let path_segment = segments.iter().last().unwrap_or_else(|| panic!(
+            let path_segment = segments.iter().last().unwrap_or_else(|| {
+                panic!(
                 "get_index_type_name(clean_type: {:?}, accept_generic: {:?}) had length zero path",
                 clean_type, accept_generic
-            ));
+            )
+            });
             Some(path_segment.name.clone())
         }
         clean::Generic(ref s) if accept_generic => Some(s.clone()),

src/librustdoc/passes/calculate_doc_coverage.rs

@@ -2,8 +2,9 @@ use crate::clean;
 use crate::config::OutputFormat;
 use crate::core::DocContext;
 use crate::fold::{self, DocFolder};
+use crate::html::markdown::{find_testable_code, ErrorCodes};
+use crate::passes::doc_test_lints::Tests;
 use crate::passes::Pass;
-
 use rustc_span::symbol::sym;
 use rustc_span::FileName;
 use serde::Serialize;
@@ -30,15 +31,19 @@ fn calculate_doc_coverage(krate: clean::Crate, ctx: &DocContext<'_>) -> clean::C
 struct ItemCount {
     total: u64,
     with_docs: u64,
+    with_examples: u64,
 }
 
 impl ItemCount {
-    fn count_item(&mut self, has_docs: bool) {
+    fn count_item(&mut self, has_docs: bool, has_doc_example: bool) {
         self.total += 1;
 
         if has_docs {
             self.with_docs += 1;
         }
+        if has_doc_example {
+            self.with_examples += 1;
+        }
     }
 
     fn percentage(&self) -> Option<f64> {
@@ -48,20 +53,33 @@ impl ItemCount {
             None
         }
     }
+
+    fn examples_percentage(&self) -> Option<f64> {
+        if self.total > 0 {
+            Some((self.with_examples as f64 * 100.0) / self.total as f64)
+        } else {
+            None
+        }
+    }
 }
 
 impl ops::Sub for ItemCount {
     type Output = Self;
 
     fn sub(self, rhs: Self) -> Self {
-        ItemCount { total: self.total - rhs.total, with_docs: self.with_docs - rhs.with_docs }
+        ItemCount {
+            total: self.total - rhs.total,
+            with_docs: self.with_docs - rhs.with_docs,
+            with_examples: self.with_examples - rhs.with_examples,
+        }
     }
 }
 
 impl ops::AddAssign for ItemCount {
     fn add_assign(&mut self, rhs: Self) {
         self.total += rhs.total;
         self.with_docs += rhs.with_docs;
+        self.with_examples += rhs.with_examples;
     }
 }
 
@@ -103,40 +121,73 @@ impl CoverageCalculator {
         let mut total = ItemCount::default();
 
         fn print_table_line() {
-            println!("+-{0:->35}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", "");
+            println!("+-{0:->35}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", "");
         }
 
-        fn print_table_record(name: &str, count: ItemCount, percentage: f64) {
+        fn print_table_record(
+            name: &str,
+            count: ItemCount,
+            percentage: f64,
+            examples_percentage: f64,
+        ) {
             println!(
-                "| {:<35} | {:>10} | {:>10} | {:>9.1}% |",
-                name, count.with_docs, count.total, percentage
+                "| {:<35} | {:>10} | {:>10} | {:>9.1}% | {:>10} | {:>9.1}% |",
+                name,
+                count.with_docs,
+                count.total,
+                percentage,
+                count.with_examples,
+                examples_percentage,
             );
         }
 
         print_table_line();
         println!(
-            "| {:<35} | {:>10} | {:>10} | {:>10} |",
-            "File", "Documented", "Total", "Percentage"
+            "| {:<35} | {:>10} | {:>10} | {:>10} | {:>10} | {:>10} |",
+            "File", "Documented", "Total", "Percentage", "Examples", "Percentage",
         );
         print_table_line();
 
         for (file, &count) in &self.items {
-            if let Some(percentage) = count.percentage() {
-                print_table_record(&limit_filename_len(file.to_string()), count, percentage);
+            if let (Some(percentage), Some(examples_percentage)) =
+                (count.percentage(), count.examples_percentage())
+            {
+                print_table_record(
+                    &limit_filename_len(file.to_string()),
+                    count,
+                    percentage,
+                    examples_percentage,
+                );
 
                 total += count;
             }
         }
 
         print_table_line();
-        print_table_record("Total", total, total.percentage().unwrap_or(0.0));
+        print_table_record(
+            "Total",
+            total,
+            total.percentage().unwrap_or(0.0),
+            total.examples_percentage().unwrap_or(0.0),
+        );
         print_table_line();
     }
 }
 
 impl fold::DocFolder for CoverageCalculator {
     fn fold_item(&mut self, i: clean::Item) -> Option<clean::Item> {
         let has_docs = !i.attrs.doc_strings.is_empty();
+        let mut tests = Tests { found_tests: 0 };
+
+        find_testable_code(
+            &i.attrs.doc_strings.iter().map(|d| d.as_str()).collect::<Vec<_>>().join("\n"),
+            &mut tests,
+            ErrorCodes::No,
+            false,
+            None,
+        );
+
+        let has_doc_example = tests.found_tests != 0;
 
         match i.inner {
             _ if !i.def_id.is_local() => {
@@ -187,7 +238,10 @@ impl fold::DocFolder for CoverageCalculator {
             }
             _ => {
                 debug!("counting {:?} {:?} in {}", i.type_(), i.name, i.source.filename);
-                self.items.entry(i.source.filename.clone()).or_default().count_item(has_docs);
+                self.items
+                    .entry(i.source.filename.clone())
+                    .or_default()
+                    .count_item(has_docs, has_doc_example);
             }
         }
 

src/librustdoc/passes/doc_test_lints.rs

@@ -43,6 +43,22 @@ impl<'a, 'tcx> DocFolder for PrivateItemDocTestLinter<'a, 'tcx> {
     }
 }
 
+pub(crate) struct Tests {
+    pub(crate) found_tests: usize,
+}
+
+impl Tests {
+    pub(crate) fn new() -> Tests {
+        Tests { found_tests: 0 }
+    }
+}
+
+impl crate::test::Tester for Tests {
+    fn add_test(&mut self, _: String, _: LangString, _: usize) {
+        self.found_tests += 1;
+    }
+}
+
 pub fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
     let hir_id = match cx.as_local_hir_id(item.def_id) {
         Some(hir_id) => hir_id,
@@ -52,17 +68,7 @@ pub fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
         }
     };
 
-    struct Tests {
-        found_tests: usize,
-    }
-
-    impl crate::test::Tester for Tests {
-        fn add_test(&mut self, _: String, _: LangString, _: usize) {
-            self.found_tests += 1;
-        }
-    }
-
-    let mut tests = Tests { found_tests: 0 };
+    let mut tests = Tests::new();
 
     find_testable_code(&dox, &mut tests, ErrorCodes::No, false, None);
 

src/test/rustdoc-ui/coverage/basic.stdout

@@ -1,7 +1,7 @@
-+-------------------------------------+------------+------------+------------+
-| File                                | Documented |      Total | Percentage |
-+-------------------------------------+------------+------------+------------+
-| ...est/rustdoc-ui/coverage/basic.rs |          7 |         14 |      50.0% |
-+-------------------------------------+------------+------------+------------+
-| Total                               |          7 |         14 |      50.0% |
-+-------------------------------------+------------+------------+------------+
++-------------------------------------+------------+------------+------------+------------+------------+
+| File                                | Documented |      Total | Percentage |   Examples | Percentage |
++-------------------------------------+------------+------------+------------+------------+------------+
+| ...est/rustdoc-ui/coverage/basic.rs |          7 |         14 |      50.0% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+
+| Total                               |          7 |         14 |      50.0% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+

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

@@ -0,0 +1,27 @@
+// compile-flags:-Z unstable-options --show-coverage
+// check-pass
+
+//! This test ensure that only rust code examples are counted.
+
+/// Doc
+///
+/// ```
+/// let x = 2;
+/// ```
+pub struct Foo;
+
+/// Doc
+///
+/// ```text
+/// yolo
+/// ```
+pub trait Bar {}
+
+/// Doc
+///
+/// ```ignore (just for the sake of this test)
+/// let x = 2;
+/// ```
+pub fn foo<T: Bar, D: ::std::fmt::Debug>(a: Foo, b: u32, c: T, d: D) -> u32 {
+    0
+}

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

@@ -0,0 +1,7 @@
++-------------------------------------+------------+------------+------------+------------+------------+
+| File                                | Documented |      Total | Percentage |   Examples | Percentage |
++-------------------------------------+------------+------------+------------+------------+------------+
+| ...tdoc-ui/coverage/doc-examples.rs |          4 |          4 |     100.0% |          2 |      50.0% |
++-------------------------------------+------------+------------+------------+------------+------------+
+| Total                               |          4 |          4 |     100.0% |          2 |      50.0% |
++-------------------------------------+------------+------------+------------+------------+------------+

src/test/rustdoc-ui/coverage/empty.stdout

@@ -1,7 +1,7 @@
-+-------------------------------------+------------+------------+------------+
-| File                                | Documented |      Total | Percentage |
-+-------------------------------------+------------+------------+------------+
-| ...est/rustdoc-ui/coverage/empty.rs |          0 |          1 |       0.0% |
-+-------------------------------------+------------+------------+------------+
-| Total                               |          0 |          1 |       0.0% |
-+-------------------------------------+------------+------------+------------+
++-------------------------------------+------------+------------+------------+------------+------------+
+| File                                | Documented |      Total | Percentage |   Examples | Percentage |
++-------------------------------------+------------+------------+------------+------------+------------+
+| ...est/rustdoc-ui/coverage/empty.rs |          0 |          1 |       0.0% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+
+| Total                               |          0 |          1 |       0.0% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+

src/test/rustdoc-ui/coverage/enums.stdout

@@ -1,7 +1,7 @@
-+-------------------------------------+------------+------------+------------+
-| File                                | Documented |      Total | Percentage |
-+-------------------------------------+------------+------------+------------+
-| ...est/rustdoc-ui/coverage/enums.rs |          6 |          8 |      75.0% |
-+-------------------------------------+------------+------------+------------+
-| Total                               |          6 |          8 |      75.0% |
-+-------------------------------------+------------+------------+------------+
++-------------------------------------+------------+------------+------------+------------+------------+
+| File                                | Documented |      Total | Percentage |   Examples | Percentage |
++-------------------------------------+------------+------------+------------+------------+------------+
+| ...est/rustdoc-ui/coverage/enums.rs |          6 |          8 |      75.0% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+
+| Total                               |          6 |          8 |      75.0% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+

src/test/rustdoc-ui/coverage/exotic.stdout

@@ -1,8 +1,8 @@
-+-------------------------------------+------------+------------+------------+
-| File                                | Documented |      Total | Percentage |
-+-------------------------------------+------------+------------+------------+
-| ...st/rustdoc-ui/coverage/exotic.rs |          1 |          1 |     100.0% |
-| <anon>                              |          2 |          2 |     100.0% |
-+-------------------------------------+------------+------------+------------+
-| Total                               |          3 |          3 |     100.0% |
-+-------------------------------------+------------+------------+------------+
++-------------------------------------+------------+------------+------------+------------+------------+
+| File                                | Documented |      Total | Percentage |   Examples | Percentage |
++-------------------------------------+------------+------------+------------+------------+------------+
+| ...st/rustdoc-ui/coverage/exotic.rs |          1 |          1 |     100.0% |          0 |       0.0% |
+| <anon>                              |          2 |          2 |     100.0% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+
+| Total                               |          3 |          3 |     100.0% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+

src/test/rustdoc-ui/coverage/json.stdout

@@ -1 +1 @@
-{"$DIR/json.rs":{"total":13,"with_docs":7}}
+{"$DIR/json.rs":{"total":13,"with_docs":7,"with_examples":0}}

src/test/rustdoc-ui/coverage/private.stdout

@@ -1,7 +1,7 @@
-+-------------------------------------+------------+------------+------------+
-| File                                | Documented |      Total | Percentage |
-+-------------------------------------+------------+------------+------------+
-| ...t/rustdoc-ui/coverage/private.rs |          4 |          7 |      57.1% |
-+-------------------------------------+------------+------------+------------+
-| Total                               |          4 |          7 |      57.1% |
-+-------------------------------------+------------+------------+------------+
++-------------------------------------+------------+------------+------------+------------+------------+
+| File                                | Documented |      Total | Percentage |   Examples | Percentage |
++-------------------------------------+------------+------------+------------+------------+------------+
+| ...t/rustdoc-ui/coverage/private.rs |          4 |          7 |      57.1% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+
+| Total                               |          4 |          7 |      57.1% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+

src/test/rustdoc-ui/coverage/statics-consts.stdout

@@ -1,7 +1,7 @@
-+-------------------------------------+------------+------------+------------+
-| File                                | Documented |      Total | Percentage |
-+-------------------------------------+------------+------------+------------+
-| ...oc-ui/coverage/statics-consts.rs |          6 |          7 |      85.7% |
-+-------------------------------------+------------+------------+------------+
-| Total                               |          6 |          7 |      85.7% |
-+-------------------------------------+------------+------------+------------+
++-------------------------------------+------------+------------+------------+------------+------------+
+| File                                | Documented |      Total | Percentage |   Examples | Percentage |
++-------------------------------------+------------+------------+------------+------------+------------+
+| ...oc-ui/coverage/statics-consts.rs |          6 |          7 |      85.7% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+
+| Total                               |          6 |          7 |      85.7% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+

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

@@ -1,7 +1,7 @@
-+-------------------------------------+------------+------------+------------+
-| File                                | Documented |      Total | Percentage |
-+-------------------------------------+------------+------------+------------+
-| ...st/rustdoc-ui/coverage/traits.rs |          6 |          7 |      85.7% |
-+-------------------------------------+------------+------------+------------+
-| Total                               |          6 |          7 |      85.7% |
-+-------------------------------------+------------+------------+------------+
++-------------------------------------+------------+------------+------------+------------+------------+
+| File                                | Documented |      Total | Percentage |   Examples | Percentage |
++-------------------------------------+------------+------------+------------+------------+------------+
+| ...st/rustdoc-ui/coverage/traits.rs |          6 |          7 |      85.7% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+
+| Total                               |          6 |          7 |      85.7% |          0 |       0.0% |
++-------------------------------------+------------+------------+------------+------------+------------+