Rollup merge of #22730 - ipetkov:lint-docs, r=alexcrichton

 This is a breaking change if missing docs are forbidden in any module or crate.

I had to add documentation to undocumented associated types in libstd and libcore, please let me know if the documentation is inadequate anywhere!

Fixes #20648

Author: Manishearth

src/libcore/iter.rs

@@ -86,6 +86,7 @@ use usize;
 #[rustc_on_unimplemented = "`{Self}` is not an iterator; maybe try calling `.iter()` or a similar \
                             method"]
 pub trait Iterator {
+    /// The type of the elements being iterated
     #[stable(feature = "rust1", since = "1.0.0")]
     type Item;
 
@@ -122,9 +123,11 @@ pub trait FromIterator<A> {
 /// Conversion into an `Iterator`
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait IntoIterator {
+    /// The type of the elements being iterated
     #[stable(feature = "rust1", since = "1.0.0")]
     type Item;
 
+    /// A container for iterating over elements of type Item
     #[stable(feature = "rust1", since = "1.0.0")]
     type IntoIter: Iterator<Item=Self::Item>;
 

src/libcore/ops.rs

@@ -184,6 +184,7 @@ macro_rules! forward_ref_binop {
 #[lang="add"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Add<RHS=Self> {
+    /// The resulting type after applying the `+` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -237,6 +238,7 @@ add_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 #[lang="sub"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Sub<RHS=Self> {
+    /// The resulting type after applying the `-` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -290,6 +292,7 @@ sub_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 #[lang="mul"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Mul<RHS=Self> {
+    /// The resulting type after applying the `*` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -343,6 +346,7 @@ mul_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 #[lang="div"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Div<RHS=Self> {
+    /// The resulting type after applying the `/` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -396,6 +400,7 @@ div_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 #[lang="rem"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Rem<RHS=Self> {
+    /// The resulting type after applying the `%` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output = Self;
 
@@ -468,6 +473,7 @@ rem_float_impl! { f64, fmod }
 #[lang="neg"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Neg {
+    /// The resulting type after applying the `-` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -544,6 +550,7 @@ neg_uint_impl! { u64, i64 }
 #[lang="not"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Not {
+    /// The resulting type after applying the `!` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -597,6 +604,7 @@ not_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 #[lang="bitand"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait BitAnd<RHS=Self> {
+    /// The resulting type after applying the `&` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -650,6 +658,7 @@ bitand_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 #[lang="bitor"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait BitOr<RHS=Self> {
+    /// The resulting type after applying the `|` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -703,6 +712,7 @@ bitor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 #[lang="bitxor"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait BitXor<RHS=Self> {
+    /// The resulting type after applying the `^` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -756,6 +766,7 @@ bitxor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 #[lang="shl"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Shl<RHS> {
+    /// The resulting type after applying the `<<` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -827,6 +838,7 @@ shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 #[lang="shr"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Shr<RHS> {
+    /// The resulting type after applying the `>>` operator
     #[stable(feature = "rust1", since = "1.0.0")]
     type Output;
 
@@ -900,6 +912,7 @@ shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 #[rustc_on_unimplemented = "the type `{Self}` cannot be indexed by `{Idx}`"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Index<Idx: ?Sized> {
+    /// The returned type after indexing
     type Output: ?Sized;
 
     /// The method for the indexing (`Foo[Bar]`) operation
@@ -1047,6 +1060,7 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
 #[lang="deref"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Deref {
+    /// The resulting type after dereferencing
     #[stable(feature = "rust1", since = "1.0.0")]
     type Target: ?Sized;
 
@@ -1122,6 +1136,7 @@ impl<'a, T: ?Sized> DerefMut for &'a mut T {
 #[stable(feature = "rust1", since = "1.0.0")]
 #[rustc_paren_sugar]
 pub trait Fn<Args> {
+    /// The returned type after the call operator is used.
     type Output;
 
     /// This is called when the call operator is used.
@@ -1133,6 +1148,7 @@ pub trait Fn<Args> {
 #[stable(feature = "rust1", since = "1.0.0")]
 #[rustc_paren_sugar]
 pub trait FnMut<Args> {
+    /// The returned type after the call operator is used.
     type Output;
 
     /// This is called when the call operator is used.
@@ -1144,6 +1160,7 @@ pub trait FnMut<Args> {
 #[stable(feature = "rust1", since = "1.0.0")]
 #[rustc_paren_sugar]
 pub trait FnOnce<Args> {
+    /// The returned type after the call operator is used.
     type Output;
 
     /// This is called when the call operator is used.

src/libcore/ptr.rs

@@ -249,6 +249,7 @@ pub unsafe fn write<T>(dst: *mut T, src: T) {
 /// Methods on raw pointers
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait PtrExt: Sized {
+    /// The type which is being pointed at
     type Target;
 
     /// Returns true if the pointer is null.
@@ -284,6 +285,7 @@ pub trait PtrExt: Sized {
 /// Methods on mutable raw pointers
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait MutPtrExt {
+    /// The type which is being pointed at
     type Target;
 
     /// Returns `None` if the pointer is null, or else returns a mutable

src/librustc/lint/builtin.rs

@@ -1577,6 +1577,14 @@ impl LintPass for MissingDoc {
                                      tm.span, "a type method");
     }
 
+    fn check_trait_method(&mut self, cx: &Context, it: &ast::TraitItem) {
+        if let ast::TraitItem::TypeTraitItem(ref ty) = *it {
+            let assoc_ty = &ty.ty_param;
+            self.check_missing_docs_attrs(cx, Some(assoc_ty.id), &ty.attrs,
+                                          assoc_ty.span, "an associated type");
+        }
+    }
+
     fn check_struct_field(&mut self, cx: &Context, sf: &ast::StructField) {
         if let ast::NamedField(_, vis) = sf.node.kind {
             if vis == ast::Public || self.in_variant {

src/libstd/ascii.rs

@@ -37,6 +37,7 @@ pub trait OwnedAsciiExt {
 /// Extension methods for ASCII-subset only operations on string slices
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait AsciiExt {
+    /// Container type for copied ASCII characters.
     #[stable(feature = "rust1", since = "1.0.0")]
     type Owned;
 

src/libstd/collections/hash/state.rs

@@ -27,6 +27,7 @@ use marker;
 /// to `Default` when asked to create a hasher.
 #[unstable(feature = "std_misc", reason = "hasher stuff is unclear")]
 pub trait HashState {
+    /// Type of the hasher that will be created.
     type Hasher: hash::Hasher;
 
     /// Creates a new hasher based on the given state of this object.

src/test/compile-fail/lint-missing-doc.rs

@@ -17,15 +17,15 @@
 #![doc="More garbage"]
 
 type Typedef = String;
-pub type PubTypedef = String; //~ ERROR: missing documentation
+pub type PubTypedef = String; //~ ERROR: missing documentation for a type alias
 
 struct Foo {
     a: isize,
     b: isize,
 }
 
-pub struct PubFoo { //~ ERROR: missing documentation
-    pub a: isize,      //~ ERROR: missing documentation
+pub struct PubFoo { //~ ERROR: missing documentation for a struct
+    pub a: isize,      //~ ERROR: missing documentation for a struct field
     b: isize,
 }
 
@@ -36,11 +36,11 @@ pub struct PubFoo2 {
 }
 
 mod module_no_dox {}
-pub mod pub_module_no_dox {} //~ ERROR: missing documentation
+pub mod pub_module_no_dox {} //~ ERROR: missing documentation for a module
 
 /// dox
 pub fn foo() {}
-pub fn foo2() {} //~ ERROR: missing documentation
+pub fn foo2() {} //~ ERROR: missing documentation for a function
 fn foo3() {}
 #[allow(missing_docs)] pub fn foo4() {}
 
@@ -58,23 +58,36 @@ trait B {
     fn foo_with_impl(&self) {}
 }
 
-pub trait C { //~ ERROR: missing documentation
-    fn foo(&self); //~ ERROR: missing documentation
-    fn foo_with_impl(&self) {} //~ ERROR: missing documentation
+pub trait C { //~ ERROR: missing documentation for a trait
+    fn foo(&self); //~ ERROR: missing documentation for a type method
+    fn foo_with_impl(&self) {} //~ ERROR: missing documentation for a method
 }
 
 #[allow(missing_docs)]
 pub trait D {
     fn dummy(&self) { }
 }
 
+/// dox
+pub trait E {
+    type AssociatedType; //~ ERROR: missing documentation for an associated type
+    type AssociatedTypeDef = Self; //~ ERROR: missing documentation for an associated type
+
+    /// dox
+    type DocumentedType;
+    /// dox
+    type DocumentedTypeDef = Self;
+    /// dox
+    fn dummy(&self) {}
+}
+
 impl Foo {
     pub fn foo() {}
     fn bar() {}
 }
 
 impl PubFoo {
-    pub fn foo() {} //~ ERROR: missing documentation
+    pub fn foo() {} //~ ERROR: missing documentation for a method
     /// dox
     pub fn foo1() {}
     fn foo2() {}
@@ -111,9 +124,9 @@ enum Baz {
     BarB
 }
 
-pub enum PubBaz { //~ ERROR: missing documentation
-    PubBazA { //~ ERROR: missing documentation
-        a: isize, //~ ERROR: missing documentation
+pub enum PubBaz { //~ ERROR: missing documentation for an enum
+    PubBazA { //~ ERROR: missing documentation for a variant
+        a: isize, //~ ERROR: missing documentation for a struct field
     },
 }
 
@@ -139,14 +152,14 @@ pub fn baz() {}
 mod internal_impl {
     /// dox
     pub fn documented() {}
-    pub fn undocumented1() {} //~ ERROR: missing documentation
-    pub fn undocumented2() {} //~ ERROR: missing documentation
+    pub fn undocumented1() {} //~ ERROR: missing documentation for a function
+    pub fn undocumented2() {} //~ ERROR: missing documentation for a function
     fn undocumented3() {}
     /// dox
     pub mod globbed {
         /// dox
         pub fn also_documented() {}
-        pub fn also_undocumented1() {} //~ ERROR: missing documentation
+        pub fn also_undocumented1() {} //~ ERROR: missing documentation for a function
         fn also_undocumented2() {}
     }
 }