2 use crate::core::DocContext;
3 use crate::fold::{self, DocFolder};
4 use crate::passes::Pass;
6 use rustc_span::symbol::sym;
7 use rustc_span::FileName;
10 use std::collections::BTreeMap;
13 pub const CALCULATE_DOC_COVERAGE: Pass = Pass {
14 name: "calculate-doc-coverage",
15 run: calculate_doc_coverage,
16 description: "counts the number of items with and without documentation",
19 fn calculate_doc_coverage(krate: clean::Crate, _: &DocContext<'_>) -> clean::Crate {
20 let mut calc = CoverageCalculator::default();
21 let krate = calc.fold_crate(krate);
28 #[derive(Default, Copy, Clone)]
35 fn count_item(&mut self, has_docs: bool) {
43 fn percentage(&self) -> Option<f64> {
45 Some((self.with_docs as f64 * 100.0) / self.total as f64)
52 impl ops::Sub for ItemCount {
55 fn sub(self, rhs: Self) -> Self {
56 ItemCount { total: self.total - rhs.total, with_docs: self.with_docs - rhs.with_docs }
60 impl ops::AddAssign for ItemCount {
61 fn add_assign(&mut self, rhs: Self) {
62 self.total += rhs.total;
63 self.with_docs += rhs.with_docs;
68 struct CoverageCalculator {
69 items: BTreeMap<FileName, ItemCount>,
72 impl CoverageCalculator {
73 fn print_results(&self) {
74 let mut total = ItemCount::default();
76 fn print_table_line() {
77 println!("+-{0:->35}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", "");
80 fn print_table_record(name: &str, count: ItemCount, percentage: f64) {
82 "| {:<35} | {:>10} | {:>10} | {:>9.1}% |",
83 name, count.with_docs, count.total, percentage
89 "| {:<35} | {:>10} | {:>10} | {:>10} |",
90 "File", "Documented", "Total", "Percentage"
94 for (file, &count) in &self.items {
95 if let Some(percentage) = count.percentage() {
96 let mut name = file.to_string();
97 // if a filename is too long, shorten it so we don't blow out the table
98 // FIXME(misdreavus): this needs to count graphemes, and probably also track
99 // double-wide characters...
101 name = "...".to_string() + &name[name.len() - 32..];
104 print_table_record(&name, count, percentage);
111 print_table_record("Total", total, total.percentage().unwrap_or(0.0));
116 impl fold::DocFolder for CoverageCalculator {
117 fn fold_item(&mut self, i: clean::Item) -> Option<clean::Item> {
118 let has_docs = !i.attrs.doc_strings.is_empty();
121 _ if !i.def_id.is_local() => {
122 // non-local items are skipped because they can be out of the users control,
123 // especially in the case of trait impls, which rustdoc eagerly inlines
126 clean::StrippedItem(..) => {
127 // don't count items in stripped modules
130 clean::ImportItem(..) | clean::ExternCrateItem(..) => {
131 // docs on `use` and `extern crate` statements are not displayed, so they're not
135 clean::ImplItem(ref impl_)
136 if attr::contains_name(&i.attrs.other_attrs, sym::automatically_derived)
138 || impl_.blanket_impl.is_some() =>
140 // built-in derives get the `#[automatically_derived]` attribute, and
141 // synthetic/blanket impls are made up by rustdoc and can't be documented
142 // FIXME(misdreavus): need to also find items that came out of a derive macro
145 clean::ImplItem(ref impl_) => {
146 if let Some(ref tr) = impl_.trait_ {
148 "impl {:#} for {:#} in {}",
154 // don't count trait impls, the missing-docs lint doesn't so we shouldn't
158 // inherent impls *can* be documented, and those docs show up, but in most
159 // cases it doesn't make sense, as all methods on a type are in one single
161 debug!("impl {:#} in {}", impl_.for_.print(), i.source.filename);
165 debug!("counting {:?} {:?} in {}", i.type_(), i.name, i.source.filename);
166 self.items.entry(i.source.filename.clone()).or_default().count_item(has_docs);
170 self.fold_item_recur(i)