Extend coverage feature

Author: GuillaumeGomez

src/db/add_package.rs

@@ -137,17 +137,24 @@ pub(crate) fn add_doc_coverage(
 ) -> Result<i32> {
     debug!("Adding doc coverage into database");
     let rows = conn.query(
-        "INSERT INTO doc_coverage (release_id, total_items, documented_items)
-            VALUES ($1, $2, $3)
+        "INSERT INTO doc_coverage (
+            release_id, total_items, documented_items,
+            total_items_needing_examples, items_with_examples
+        )
+            VALUES ($1, $2, $3, $4, $5)
             ON CONFLICT (release_id) DO UPDATE
                 SET
                     total_items = $2,
-                    documented_items = $3
+                    documented_items = $3,
+                    total_items_needing_examples = $4,
+                    items_with_examples = $5
             RETURNING release_id",
         &[
             &release_id,
             &doc_coverage.total_items,
             &doc_coverage.documented_items,
+            &doc_coverage.total_items_needing_examples,
+            &doc_coverage.items_with_examples,
         ],
     )?;
     Ok(rows[0].get(0))

src/db/migrate.rs

@@ -438,6 +438,25 @@ pub fn migrate(version: Option<Version>, conn: &mut Client) -> CratesfyiResult<(
             ALTER TABLE owners ALTER COLUMN name DROP NOT NULL;
             ALTER TABLE crates ALTER COLUMN github_stars DROP NOT NULL;
             "
+        ),
+        migration!(
+            context,
+            // version
+            18,
+            // description
+            "Add more information into doc coverage",
+            // upgrade query
+            "
+            ALTER TABLE doc_coverage
+                ADD COLUMN total_items_needing_examples INT,
+                ADD COLUMN items_with_examples INT;
+            ",
+            // downgrade query
+            "
+            ALTER TABLE doc_coverage
+                DROP COLUMN total_items_needing_examples,
+                DROP COLUMN items_with_examples;
+            "
         )
     ];
 

src/docbuilder/rustwide_builder.rs

@@ -455,11 +455,15 @@ impl RustwideBuilder {
         struct FileCoverage {
             total: i32,
             with_docs: i32,
+            total_examples: i32,
+            with_examples: i32,
         }
 
         let mut coverage = DocCoverage {
             total_items: 0,
             documented_items: 0,
+            total_items_needing_examples: 0,
+            items_with_examples: 0,
         };
 
         self.prepare_command(build, target, metadata, limits, rustdoc_flags)?
@@ -472,6 +476,8 @@ impl RustwideBuilder {
                     for file in parsed.values() {
                         coverage.total_items += file.total;
                         coverage.documented_items += file.with_docs;
+                        coverage.total_items_needing_examples += file.total_examples;
+                        coverage.items_with_examples += file.with_examples;
                     }
                 }
             })
@@ -670,6 +676,11 @@ pub(crate) struct DocCoverage {
     pub(crate) total_items: i32,
     /// The items of the crate that are documented, used to calculate documentation coverage.
     pub(crate) documented_items: i32,
+    /// The total items that could have code examples in the current crate, used to calculate
+    /// documentation coverage.
+    pub(crate) total_items_needing_examples: i32,
+    /// The items of the crate that have a code example, used to calculate documentation coverage.
+    pub(crate) items_with_examples: i32,
 }
 
 pub(crate) struct BuildResult {

src/test/fakes.rs

@@ -183,10 +183,18 @@ impl<'a> FakeRelease<'a> {
         self
     }
 
-    pub(crate) fn coverage(mut self, documented_items: i32, total_items: i32) -> Self {
+    pub(crate) fn coverage(
+        mut self,
+        documented_items: i32,
+        total_items: i32,
+        total_items_needing_examples: i32,
+        items_with_examples: i32,
+    ) -> Self {
         self.build_result.doc_coverage = Some(DocCoverage {
             total_items,
             documented_items,
+            total_items_needing_examples,
+            items_with_examples,
         });
         self
     }

src/web/crate_details.rs

@@ -45,6 +45,8 @@ pub struct CrateDetails {
     documentation_url: Option<String>,
     total_items: Option<f32>,
     documented_items: Option<f32>,
+    total_items_needing_examples: Option<f32>,
+    items_with_examples: Option<f32>,
 }
 
 fn optional_markdown<S>(markdown: &Option<String>, serializer: S) -> Result<S::Ok, S::Error>
@@ -100,7 +102,9 @@ impl CrateDetails {
                 releases.documentation_url,
                 releases.default_target,
                 doc_coverage.total_items,
-                doc_coverage.documented_items
+                doc_coverage.documented_items,
+                COALESCE(doc_coverage.total_items_needing_examples, 0) AS total_items_needing_examples,
+                COALESCE(doc_coverage.items_with_examples, 0) AS items_with_examples
             FROM releases
             INNER JOIN crates ON releases.crate_id = crates.id
             LEFT JOIN doc_coverage ON doc_coverage.release_id = releases.id
@@ -156,6 +160,8 @@ impl CrateDetails {
 
         let documented_items: Option<i32> = krate.get("documented_items");
         let total_items: Option<i32> = krate.get("total_items");
+        let total_items_needing_examples: Option<i32> = krate.get("total_items_needing_examples");
+        let items_with_examples: Option<i32> = krate.get("items_with_examples");
 
         let mut crate_details = CrateDetails {
             name: krate.get("name"),
@@ -189,6 +195,8 @@ impl CrateDetails {
             documentation_url: krate.get("documentation_url"),
             documented_items: documented_items.map(|v| v as f32),
             total_items: total_items.map(|v| v as f32),
+            total_items_needing_examples: total_items_needing_examples.map(|v| v as f32),
+            items_with_examples: items_with_examples.map(|v| v as f32),
         };
 
         if let Some(repository_url) = crate_details.repository_url.clone() {

src/web/mod.rs

@@ -644,12 +644,13 @@ mod test {
                 .name("foo")
                 .version("0.0.1")
                 .source_file("test.rs", &[])
-                .coverage(6, 10)
+                .coverage(6, 10, 2, 1)
                 .create()?;
             let web = env.frontend();
 
             let foo_crate = kuchiki::parse_html().one(web.get("/crate/foo/0.0.1").send()?.text()?);
-            for value in &["60%", "6", "10"] {
+            // 58% = ((6 * 100 / 10) * 8 + (1 * 100 / 2) * 2) / 10
+            for value in &["58%", "6", "10", "2", "1"] {
                 assert!(foo_crate
                     .select(".pure-menu-item b")
                     .unwrap()
@@ -660,7 +661,7 @@ mod test {
             assert!(foo_doc
                 .select(".pure-menu-link b")
                 .unwrap()
-                .any(|e| e.text_contents().contains("60%")));
+                .any(|e| e.text_contents().contains("58%")));
 
             Ok(())
         });

templates/crate/details.html

@@ -17,10 +17,10 @@
                 <div class="pure-menu package-menu">
                     <ul class="pure-menu-list">
                         {%- if details.documented_items and details.total_items -%}
-                            {% set percent = details.documented_items * 100 / details.total_items %}
                             <li class="pure-menu-heading">Coverage</li>
-                            <li class="pure-menu-item" style="text-align:center;"><b>{{ percent | round(precision=2) }}%</b><br>
-                                <span style="font-size: 13px;"><b>{{ details.documented_items }}</b> out of <b>{{ details.total_items }}</b> items documented</span>
+                            <li class="pure-menu-item" style="text-align:center;"><b>{{ macros::compute_doc_coverage(documented_items=details.documented_items, total_items=details.total_items, items_with_examples=details.items_with_examples, total_items_needing_examples=details.total_items_needing_examples) }}</b><br>
+                                <span class="documented-info"><b>{{ details.documented_items }}</b> out of <b>{{ details.total_items }}</b> items documented</span>
+                                <span style="font-size: 13px;"><b>{{ details.items_with_examples }}</b> out of <b>{{ details.total_items_needing_examples }}</b> items with examples</span>
                             </li>
                         {%- endif -%}
                         {# List the release author's names and a link to their docs.rs profile #}

templates/macros.html

@@ -164,3 +164,15 @@
         </li>
     {%- endfor -%}
 {% endmacro releases_list %}
+
+{% macro compute_doc_coverage(documented_items, total_items, items_with_examples, total_items_needing_examples) %}
+    {%- if total_items_needing_examples > 0 -%}
+        {%- set percent_examples = items_with_examples * 100 / total_items_needing_examples -%}
+    {%- else -%}
+        {% set percent_examples = 100 %}
+    {%- endif -%}
+    {%- set percent_doc = (documented_items * 100 / total_items) -%}
+    {# The computation is as follow: documentation is account for 80% and code examples for 20% #}
+    {%- set percent = (percent_doc * 8 + percent_examples * 2) / 10 -%}
+    {{ percent | round(precision=2) }}%
+{% endmacro compute_doc_coverage %}

templates/rustdoc/header.html

@@ -161,7 +161,7 @@
                                         <ul class="pure-menu-list">
                                             <li>
                                                 <a href="{{ crate_url | safe }}" class="pure-menu-link">
-                                                    <b>{{ percent | round(precision=2) }}%</b>
+                                                    <b>{{ macros::compute_doc_coverage(documented_items=krate.documented_items, total_items=krate.total_items, items_with_examples=krate.items_with_examples, total_items_needing_examples=krate.total_items_needing_examples) }}</b>
                                                     of the crate is documented
                                                 </a>
                                             </li>

templates/style/base.scss

@@ -311,6 +311,12 @@ div.package-page-container {
             margin: 20px 5px 15px 5px;
         }
 
+        li.pure-menu-item > .documented-info {
+            font-size: 13px;
+            display: block;
+            width: 100%;
+        }
+
         li.pure-menu-heading:first-child {
             margin-top: 0;
         }