use crate::clean; use crate::core::DocContext; use crate::html::item_type::ItemType; use crate::fold::{self, DocFolder}; use crate::passes::Pass; use syntax::attr; use std::collections::BTreeMap; use std::fmt; use std::ops; pub const CALCULATE_DOC_COVERAGE: Pass = Pass { name: "calculate-doc-coverage", pass: calculate_doc_coverage, description: "counts the number of items with and without documentation", }; fn calculate_doc_coverage(krate: clean::Crate, _: &DocContext<'_, '_, '_>) -> clean::Crate { let mut calc = CoverageCalculator::default(); let krate = calc.fold_crate(krate); calc.print_results(); krate } #[derive(Default, Copy, Clone)] struct ItemCount { total: u64, with_docs: u64, } impl ItemCount { fn count_item(&mut self, has_docs: bool) { self.total += 1; if has_docs { self.with_docs += 1; } } fn percentage(&self) -> Option { if self.total > 0 { Some((self.with_docs 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, } } } impl ops::AddAssign for ItemCount { fn add_assign(&mut self, rhs: Self) { self.total += rhs.total; self.with_docs += rhs.with_docs; } } impl fmt::Display for ItemCount { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{}/{}", self.with_docs, self.total) } } #[derive(Default)] struct CoverageCalculator { items: BTreeMap, } impl CoverageCalculator { fn print_results(&self) { use crate::html::item_type::ItemType::*; let mut total = ItemCount::default(); let main_types = [ Module, Function, Struct, StructField, Enum, Variant, Union, Method, Trait, TyMethod, AssociatedType, AssociatedConst, Macro, Static, Constant, ForeignType, Existential, Typedef, TraitAlias, Primitive, Keyword, ]; println!("+-{0:->25}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", ""); println!("| {:<25} | {:>10} | {:>10} | {:>10} |", "Item Type", "Documented", "Total", "Percentage"); println!("+-{0:->25}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", ""); for item_type in &main_types { let count = self.items.get(item_type).cloned().unwrap_or_default(); if let Some(percentage) = count.percentage() { println!("| {:<25} | {:>10} | {:>10} | {:>9.1}% |", table_name(item_type), count.with_docs, count.total, percentage); total += count; } } println!("+-{0:->25}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", ""); if let Some(count) = self.items.get(&Impl) { if let Some(percentage) = count.percentage() { if let Some(percentage) = total.percentage() { println!("| {:<25} | {:>10} | {:>10} | {:>9.1}% |", "Total (non trait impls)", total.with_docs, total.total, percentage); } println!("+-{0:->25}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", ""); println!("| {:<25} | {:>10} | {:>10} | {:>9.1}% |", table_name(&Impl), count.with_docs, count.total, percentage); println!("+-{0:->25}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", ""); total += *count; } } println!("| {:<25} | {:>10} | {:>10} | {:>9.1}% |", "Total", total.with_docs, total.total, total.percentage().unwrap_or(0.0)); println!("+-{0:->25}-+-{0:->10}-+-{0:->10}-+-{0:->10}-+", ""); } } impl fold::DocFolder for CoverageCalculator { fn fold_item(&mut self, mut i: clean::Item) -> Option { let has_docs = !i.attrs.doc_strings.is_empty(); match i.inner { _ if !i.def_id.is_local() => { // non-local items are skipped because they can be out of the users control, // especially in the case of trait impls, which rustdoc eagerly inlines return Some(i); } clean::StrippedItem(..) => { // don't count items in stripped modules return Some(i); } clean::ImportItem(..) | clean::ExternCrateItem(..) => { // docs on `use` and `extern crate` statements are not displayed, so they're not // worth counting return Some(i); } clean::ImplItem(ref impl_) if attr::contains_name(&i.attrs.other_attrs, "automatically_derived") || impl_.synthetic || impl_.blanket_impl.is_some() => { // built-in derives get the `#[automatically_derived]` attribute, and // synthetic/blanket impls are made up by rustdoc and can't be documented // FIXME(misdreavus): need to also find items that came out of a derive macro return Some(i); } clean::ImplItem(ref impl_) => { if let Some(ref tr) = impl_.trait_ { debug!("counting impl {:#} for {:#}", tr, impl_.for_); // trait impls inherit their docs from the trait definition, so documenting // them can be considered optional self.items.entry(ItemType::Impl).or_default().count_item(has_docs); for it in &impl_.items { let has_docs = !it.attrs.doc_strings.is_empty(); self.items.entry(ItemType::Impl).or_default().count_item(has_docs); } // now skip recursing, so that we don't double-count this impl's items return Some(i); } else { // inherent impls *can* be documented, and those docs show up, but in most // cases it doesn't make sense, as all methods on a type are in one single // impl block debug!("not counting impl {:#}", impl_.for_); } } clean::MacroItem(..) | clean::ProcMacroItem(..) => { // combine `macro_rules!` macros and proc-macros in the same count debug!("counting macro {:?}", i.name); self.items.entry(ItemType::Macro).or_default().count_item(has_docs); } clean::TraitItem(ref mut trait_) => { // because both trait methods with a default impl and struct methods are // ItemType::Method, we need to properly tag trait methods as TyMethod instead debug!("counting trait {:?}", i.name); self.items.entry(ItemType::Trait).or_default().count_item(has_docs); // since we're not going on to document the crate, it doesn't matter if we discard // the item after counting it trait_.items.retain(|it| { if it.type_() == ItemType::Method { let has_docs = !it.attrs.doc_strings.is_empty(); self.items.entry(ItemType::TyMethod).or_default().count_item(has_docs); false } else { true } }); } _ => { debug!("counting {} {:?}", i.type_(), i.name); self.items.entry(i.type_()).or_default().count_item(has_docs); } } self.fold_item_recur(i) } } fn table_name(type_: &ItemType) -> &'static str { match *type_ { ItemType::Module => "Modules", ItemType::Struct => "Structs", ItemType::Union => "Unions", ItemType::Enum => "Enums", ItemType::Function => "Functions", ItemType::Typedef => "Type Aliases", ItemType::Static => "Statics", ItemType::Trait => "Traits", // inherent impls aren't counted, and trait impls get all their items thrown into this // counter ItemType::Impl => "Trait Impl Items", // even though trait methods with a default impl get cleaned as Method, we convert them // to TyMethod when counting ItemType::TyMethod => "Trait Methods", ItemType::Method => "Methods", ItemType::StructField => "Struct Fields", ItemType::Variant => "Enum Variants", ItemType::Macro => "Macros", ItemType::Primitive => "Primitives", ItemType::AssociatedType => "Associated Types", ItemType::Constant => "Constants", ItemType::AssociatedConst => "Associated Constants", ItemType::ForeignType => "Extern Types", ItemType::Keyword => "Keywords", ItemType::Existential => "Existential Types", ItemType::TraitAlias => "Trait Aliases", _ => panic!("unanticipated ItemType: {}", type_), } }