From dab394c2db5d62dce64ac13af35bb2f18357c9d8 Mon Sep 17 00:00:00 2001 From: Ivan Petkov Date: Mon, 23 Feb 2015 11:05:55 -0800 Subject: [PATCH 1/3] Add documentation to associated types in libcore, libstd --- src/libcore/iter.rs | 3 +++ src/libcore/ops.rs | 17 +++++++++++++++++ src/libcore/ptr.rs | 2 ++ src/libstd/ascii.rs | 1 + src/libstd/collections/hash/state.rs | 1 + 5 files changed, 24 insertions(+) diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index 2d50bbb641363..09089f2d04c5f 100644 --- a/src/libcore/iter.rs +++ b/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 { /// 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; diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index fbd7f840da6e1..c382ac46d5db9 100644 --- a/src/libcore/ops.rs +++ b/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 { + /// 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 { + /// 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 { + /// 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 { + /// 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 { + /// 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 { + /// 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 { + /// 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 { + /// 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 { + /// 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 { + /// 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 { + /// The returned type after indexing type Output: ?Sized; /// The method for the indexing (`Foo[Bar]`) operation @@ -1047,6 +1060,7 @@ impl fmt::Debug for RangeTo { #[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 { + /// 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 { #[stable(feature = "rust1", since = "1.0.0")] #[rustc_paren_sugar] pub trait FnMut { + /// 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 { #[stable(feature = "rust1", since = "1.0.0")] #[rustc_paren_sugar] pub trait FnOnce { + /// The returned type after the call operator is used. type Output; /// This is called when the call operator is used. diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs index 16b84dcf18e24..b44cc899787f5 100644 --- a/src/libcore/ptr.rs +++ b/src/libcore/ptr.rs @@ -249,6 +249,7 @@ pub unsafe fn write(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 diff --git a/src/libstd/ascii.rs b/src/libstd/ascii.rs index 4d38d17576ddb..94457a5d71441 100644 --- a/src/libstd/ascii.rs +++ b/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; diff --git a/src/libstd/collections/hash/state.rs b/src/libstd/collections/hash/state.rs index 7e6dd45b51e48..3a06d2d03bf3f 100644 --- a/src/libstd/collections/hash/state.rs +++ b/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. From 717a91d6651598994834d056c69e6c4bf2b74b9f Mon Sep 17 00:00:00 2001 From: Ivan Petkov Date: Mon, 23 Feb 2015 11:07:37 -0800 Subject: [PATCH 2/3] Update missing-docs lint to check associated type declarations [breaking-change] Fixes #20648 --- src/librustc/lint/builtin.rs | 8 ++++++++ src/test/compile-fail/lint-missing-doc.rs | 13 +++++++++++++ 2 files changed, 21 insertions(+) diff --git a/src/librustc/lint/builtin.rs b/src/librustc/lint/builtin.rs index 3c06bae177cef..66799adef2afd 100644 --- a/src/librustc/lint/builtin.rs +++ b/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 { diff --git a/src/test/compile-fail/lint-missing-doc.rs b/src/test/compile-fail/lint-missing-doc.rs index 73a58741bbbbc..f5ce85ab325d7 100644 --- a/src/test/compile-fail/lint-missing-doc.rs +++ b/src/test/compile-fail/lint-missing-doc.rs @@ -68,6 +68,19 @@ pub trait D { fn dummy(&self) { } } +/// dox +pub trait E { + type AssociatedType; //~ ERROR: missing documentation + type AssociatedTypeDef = Self; //~ ERROR: missing documentation + + /// dox + type DocumentedType; + /// dox + type DocumentedTypeDef = Self; + /// dox + fn dummy(&self) {} +} + impl Foo { pub fn foo() {} fn bar() {} From 2e9521c126214255c8d7a78db4daf431bb5d6320 Mon Sep 17 00:00:00 2001 From: Ivan Petkov Date: Mon, 23 Feb 2015 11:33:52 -0800 Subject: [PATCH 3/3] Update missing-doc test to explicitly check errors This way we can be sure the correct error is displayed for the respective code type. --- src/test/compile-fail/lint-missing-doc.rs | 34 +++++++++++------------ 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/src/test/compile-fail/lint-missing-doc.rs b/src/test/compile-fail/lint-missing-doc.rs index f5ce85ab325d7..cb2d4e10e6e71 100644 --- a/src/test/compile-fail/lint-missing-doc.rs +++ b/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,9 +58,9 @@ 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)] @@ -70,8 +70,8 @@ pub trait D { /// dox pub trait E { - type AssociatedType; //~ ERROR: missing documentation - type AssociatedTypeDef = Self; //~ ERROR: missing documentation + type AssociatedType; //~ ERROR: missing documentation for an associated type + type AssociatedTypeDef = Self; //~ ERROR: missing documentation for an associated type /// dox type DocumentedType; @@ -87,7 +87,7 @@ impl Foo { } impl PubFoo { - pub fn foo() {} //~ ERROR: missing documentation + pub fn foo() {} //~ ERROR: missing documentation for a method /// dox pub fn foo1() {} fn foo2() {} @@ -124,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 }, } @@ -152,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() {} } }