diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/librustdoc/html/item_type.rs | 2 | ||||
| -rw-r--r-- | src/librustdoc/passes/calculate_doc_coverage.rs | 206 |
2 files changed, 166 insertions, 42 deletions
diff --git a/src/librustdoc/html/item_type.rs b/src/librustdoc/html/item_type.rs index 353fa4ae8c9..366e60b3ad9 100644 --- a/src/librustdoc/html/item_type.rs +++ b/src/librustdoc/html/item_type.rs @@ -15,7 +15,7 @@ use crate::clean; /// module headings. If you are adding to this enum and want to ensure that the sidebar also prints /// a heading, edit the listing in `html/render.rs`, function `sidebar_module`. This uses an /// ordering based on a helper function inside `item_module`, in the same file. -#[derive(Copy, PartialEq, Clone, Debug)] +#[derive(Copy, PartialEq, Eq, Clone, Debug, PartialOrd, Ord)] pub enum ItemType { Module = 0, ExternCrate = 1, diff --git a/src/librustdoc/passes/calculate_doc_coverage.rs b/src/librustdoc/passes/calculate_doc_coverage.rs index cb6d180fbd3..06f9a604ec8 100644 --- a/src/librustdoc/passes/calculate_doc_coverage.rs +++ b/src/librustdoc/passes/calculate_doc_coverage.rs @@ -1,12 +1,14 @@ 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::ops::Sub; +use std::collections::BTreeMap; use std::fmt; +use std::ops; pub const CALCULATE_DOC_COVERAGE: Pass = Pass { name: "calculate-doc-coverage", @@ -18,17 +20,7 @@ fn calculate_doc_coverage(krate: clean::Crate, _: &DocContext<'_, '_, '_>) -> cl let mut calc = CoverageCalculator::default(); let krate = calc.fold_crate(krate); - let non_traits = calc.items - calc.trait_impl_items; - - print!("Rustdoc found {} items with documentation", calc.items); - println!(" ({} not counting trait impls)", non_traits); - - if let (Some(percentage), Some(percentage_non_traits)) = - (calc.items.percentage(), non_traits.percentage()) - { - println!(" Score: {:.1}% ({:.1}% not counting trait impls)", - percentage, percentage_non_traits); - } + calc.print_results(); krate } @@ -57,7 +49,7 @@ impl ItemCount { } } -impl Sub for ItemCount { +impl ops::Sub for ItemCount { type Output = Self; fn sub(self, rhs: Self) -> Self { @@ -68,6 +60,13 @@ impl Sub for ItemCount { } } +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) @@ -76,58 +75,183 @@ impl fmt::Display for ItemCount { #[derive(Default)] struct CoverageCalculator { - items: ItemCount, - trait_impl_items: ItemCount, + items: BTreeMap<ItemType, ItemCount>, +} + +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, i: clean::Item) -> Option<clean::Item> { + fn fold_item(&mut self, mut i: clean::Item) -> Option<clean::Item> { + 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(..) => {} + 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() => { - // skip counting anything inside these impl blocks + // 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); } - // 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 - _ => if i.def_id.is_local() { - let has_docs = !i.attrs.doc_strings.is_empty(); - - if let clean::ImplItem(ref i) = i.inner { - if let Some(ref tr) = i.trait_ { - debug!("counting impl {:#} for {:#}", tr, i.for_); + clean::ImplItem(ref impl_) => { + if let Some(ref tr) = impl_.trait_ { + debug!("counting impl {:#} for {:#}", tr, impl_.for_); - self.items.count_item(has_docs); + // 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); - // trait impls inherit their docs from the trait definition, so documenting - // them can be considered optional + 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); + } - self.trait_impl_items.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); - for it in &i.items { - self.trait_impl_items.count_item(!it.attrs.doc_strings.is_empty()); - } + // 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 { - // 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 {:#}", i.for_); + true } - } else { - debug!("counting {} {:?}", i.type_(), i.name); - self.items.count_item(has_docs); - } + }); + } + _ => { + 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 => "Foreign Types", + ItemType::Keyword => "Keywords", + ItemType::Existential => "Existential Types", + ItemType::TraitAlias => "Trait Aliases", + _ => panic!("unanticipated ItemType: {}", type_), + } +} |