clippy_lints/src/missing_doc.rs

   1 // This file incorporates work covered by the following copyright and
   2 // permission notice:
   3 //   Copyright 2012-2015 The Rust Project Developers. See the COPYRIGHT
   4 //   file at the top-level directory of this distribution and at
   5 //   http://rust-lang.org/COPYRIGHT.
   6 //
   7 //   Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   8 //   http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   9 //   <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
  10 //   option. This file may not be copied, modified, or distributed
  11 //   except according to those terms.
  12 //
  13
  14 // Note: More specifically this lint is largely inspired (aka copied) from
  15 // *rustc*'s
  16 // [`missing_doc`].
  17 //
  18 // [`missing_doc`]:
  19 // https://github.
  20 // com/rust-lang/rust/blob/d6d05904697d89099b55da3331155392f1db9c00/src/librustc_lint/builtin.
  21 //
  22 //
  23 //
  24 //
  25 // rs#L246
  26 //
  27
  28 use rustc::hir;
  29 use rustc::lint::*;
  30 use rustc::ty;
  31 use syntax::ast;
  32 use syntax::attr;
  33 use syntax::codemap::Span;
  34 use utils::in_macro;
  35
  36 /// **What it does:** Warns if there is missing doc for any documentable item
  37 /// (public or private).
  38 ///
  39 /// **Why is this bad?** Doc is good. *rustc* has a `MISSING_DOCS`
  40 /// allowed-by-default lint for
  41 /// public members, but has no way to enforce documentation of private items.
  42 /// This lint fixes that.
  43 ///
  44 /// **Known problems:** None.
  45 declare_lint! {
  46     pub MISSING_DOCS_IN_PRIVATE_ITEMS,
  47     Allow,
  48     "detects missing documentation for public and private members"
  49 }
  50
  51 pub struct MissingDoc {
  52     /// Stack of whether #[doc(hidden)] is set
  53     /// at each level which has lint attributes.
  54     doc_hidden_stack: Vec<bool>,
  55 }
  56
  57 impl ::std::default::Default for MissingDoc {
  58     fn default() -> MissingDoc {
  59         MissingDoc::new()
  60     }
  61 }
  62
  63 impl MissingDoc {
  64     pub fn new() -> MissingDoc {
  65         MissingDoc { doc_hidden_stack: vec![false] }
  66     }
  67
  68     fn doc_hidden(&self) -> bool {
  69         *self.doc_hidden_stack.last().expect(
  70             "empty doc_hidden_stack",
  71         )
  72     }
  73
  74     fn check_missing_docs_attrs(&self, cx: &LateContext, attrs: &[ast::Attribute], sp: Span, desc: &'static str) {
  75         // If we're building a test harness, then warning about
  76         // documentation is probably not really relevant right now.
  77         if cx.sess().opts.test {
  78             return;
  79         }
  80
  81         // `#[doc(hidden)]` disables missing_docs check.
  82         if self.doc_hidden() {
  83             return;
  84         }
  85
  86         if in_macro(sp) {
  87             return;
  88         }
  89
  90         let has_doc = attrs.iter().any(|a| {
  91             a.is_value_str() && a.name().map_or(false, |n| n == "doc")
  92         });
  93         if !has_doc {
  94             cx.span_lint(
  95                 MISSING_DOCS_IN_PRIVATE_ITEMS,
  96                 sp,
  97                 &format!("missing documentation for {}", desc),
  98             );
  99         }
 100     }
 101 }
 102
 103 impl LintPass for MissingDoc {
 104     fn get_lints(&self) -> LintArray {
 105         lint_array![MISSING_DOCS_IN_PRIVATE_ITEMS]
 106     }
 107 }
 108
 109 impl<'a, 'tcx> LateLintPass<'a, 'tcx> for MissingDoc {
 110     fn enter_lint_attrs(&mut self, _: &LateContext<'a, 'tcx>, attrs: &'tcx [ast::Attribute]) {
 111         let doc_hidden = self.doc_hidden() ||
 112             attrs.iter().any(|attr| {
 113                 attr.check_name("doc") &&
 114                     match attr.meta_item_list() {
 115                         None => false,
 116                         Some(l) => attr::list_contains_name(&l[..], "hidden"),
 117                     }
 118             });
 119         self.doc_hidden_stack.push(doc_hidden);
 120     }
 121
 122     fn exit_lint_attrs(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx [ast::Attribute]) {
 123         self.doc_hidden_stack.pop().expect("empty doc_hidden_stack");
 124     }
 125
 126     fn check_crate(&mut self, cx: &LateContext<'a, 'tcx>, krate: &'tcx hir::Crate) {
 127         self.check_missing_docs_attrs(cx, &krate.attrs, krate.span, "crate");
 128     }
 129
 130     fn check_item(&mut self, cx: &LateContext<'a, 'tcx>, it: &'tcx hir::Item) {
 131         let desc = match it.node {
 132             hir::ItemConst(..) => "a constant",
 133             hir::ItemEnum(..) => "an enum",
 134             hir::ItemFn(..) => "a function",
 135             hir::ItemMod(..) => "a module",
 136             hir::ItemStatic(..) => "a static",
 137             hir::ItemStruct(..) => "a struct",
 138             hir::ItemTrait(..) => "a trait",
 139             hir::ItemGlobalAsm(..) => "an assembly blob",
 140             hir::ItemTy(..) => "a type alias",
 141             hir::ItemUnion(..) => "a union",
 142             hir::ItemDefaultImpl(..) |
 143             hir::ItemExternCrate(..) |
 144             hir::ItemForeignMod(..) |
 145             hir::ItemImpl(..) |
 146             hir::ItemUse(..) => return,
 147         };
 148
 149         self.check_missing_docs_attrs(cx, &it.attrs, it.span, desc);
 150     }
 151
 152     fn check_trait_item(&mut self, cx: &LateContext<'a, 'tcx>, trait_item: &'tcx hir::TraitItem) {
 153         let desc = match trait_item.node {
 154             hir::TraitItemKind::Const(..) => "an associated constant",
 155             hir::TraitItemKind::Method(..) => "a trait method",
 156             hir::TraitItemKind::Type(..) => "an associated type",
 157         };
 158
 159         self.check_missing_docs_attrs(cx, &trait_item.attrs, trait_item.span, desc);
 160     }
 161
 162     fn check_impl_item(&mut self, cx: &LateContext<'a, 'tcx>, impl_item: &'tcx hir::ImplItem) {
 163         // If the method is an impl for a trait, don't doc.
 164         let def_id = cx.tcx.hir.local_def_id(impl_item.id);
 165         match cx.tcx.associated_item(def_id).container {
 166             ty::TraitContainer(_) => return,
 167             ty::ImplContainer(cid) => {
 168                 if cx.tcx.impl_trait_ref(cid).is_some() {
 169                     return;
 170                 }
 171             },
 172         }
 173
 174         let desc = match impl_item.node {
 175             hir::ImplItemKind::Const(..) => "an associated constant",
 176             hir::ImplItemKind::Method(..) => "a method",
 177             hir::ImplItemKind::Type(_) => "an associated type",
 178         };
 179         self.check_missing_docs_attrs(cx, &impl_item.attrs, impl_item.span, desc);
 180     }
 181
 182     fn check_struct_field(&mut self, cx: &LateContext<'a, 'tcx>, sf: &'tcx hir::StructField) {
 183         if !sf.is_positional() {
 184             self.check_missing_docs_attrs(cx, &sf.attrs, sf.span, "a struct field");
 185         }
 186     }
 187
 188     fn check_variant(&mut self, cx: &LateContext<'a, 'tcx>, v: &'tcx hir::Variant, _: &hir::Generics) {
 189         self.check_missing_docs_attrs(cx, &v.node.attrs, v.span, "a variant");
 190     }
 191 }