From af995ce1e7fe8c30c8f5da3d04e0e2e89762bde4 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 28 May 2013 15:44:53 -0500 Subject: [PATCH 1/4] Make missing documentation linting more robust Add some more cases for warning about missing documentation, and also add a test to make sure it doesn't die in the future. --- src/librustc/front/intrinsic.rs | 2 + src/librustc/middle/lint.rs | 178 +++++++++++++--------- src/test/compile-fail/lint-missing-doc.rs | 72 +++++++++ 3 files changed, 177 insertions(+), 75 deletions(-) create mode 100644 src/test/compile-fail/lint-missing-doc.rs diff --git a/src/librustc/front/intrinsic.rs b/src/librustc/front/intrinsic.rs index ece53451ccf80..fcb08180a5ea2 100644 --- a/src/librustc/front/intrinsic.rs +++ b/src/librustc/front/intrinsic.rs @@ -12,6 +12,8 @@ // and injected into each crate the compiler builds. Keep it small. pub mod intrinsic { + #[allow(missing_doc)]; + pub use intrinsic::rusti::visit_tydesc; // FIXME (#3727): remove this when the interface has settled and the diff --git a/src/librustc/middle/lint.rs b/src/librustc/middle/lint.rs index 56c024f12ae08..c42c8b8bb8477 100644 --- a/src/librustc/middle/lint.rs +++ b/src/librustc/middle/lint.rs @@ -95,8 +95,7 @@ pub enum lint { unused_mut, unnecessary_allocation, - missing_struct_doc, - missing_trait_doc, + missing_doc, } pub fn level_to_str(lv: level) -> &'static str { @@ -268,17 +267,10 @@ static lint_table: &'static [(&'static str, LintSpec)] = &[ default: warn }), - ("missing_struct_doc", + ("missing_doc", LintSpec { - lint: missing_struct_doc, - desc: "detects missing documentation for structs", - default: allow - }), - - ("missing_trait_doc", - LintSpec { - lint: missing_trait_doc, - desc: "detects missing documentation for traits", + lint: missing_doc, + desc: "detects missing documentation for public members", default: allow }), ]; @@ -302,6 +294,9 @@ struct Context { curr: SmallIntMap<(level, LintSource)>, // context we're checking in (used to access fields like sess) tcx: ty::ctxt, + // Just a simple flag if we're currently recursing into a trait + // implementation. This is only used by the lint_missing_doc() pass + in_trait_impl: bool, // When recursing into an attributed node of the ast which modifies lint // levels, this stack keeps track of the previous lint levels of whatever // was modified. @@ -311,7 +306,15 @@ struct Context { // Others operate directly on @ast::item structures (or similar). Finally, // others still are added to the Session object via `add_lint`, and these // are all passed with the lint_session visitor. - visitors: ~[visit::vt<@mut Context>], + // + // This is a pair so every visitor can visit every node. When a lint pass is + // registered, another visitor is created which stops at all items which can + // alter the attributes of the ast. This "item stopping visitor" is the + // second element of the pair, while the original visitor is the first + // element. This means that when visiting a node, the original recursive + // call can used the original visitor's method, although the recursing + // visitor supplied to the method is the item stopping visitor. + visitors: ~[(visit::vt<@mut Context>, visit::vt<@mut Context>)], } impl Context { @@ -429,19 +432,21 @@ impl Context { } fn add_lint(&mut self, v: visit::vt<@mut Context>) { - self.visitors.push(item_stopping_visitor(v)); + self.visitors.push((v, item_stopping_visitor(v))); } fn process(@mut self, n: AttributedNode) { + // see comment of the `visitors` field in the struct for why there's a + // pair instead of just one visitor. match n { Item(it) => { - for self.visitors.each |v| { - visit::visit_item(it, self, *v); + for self.visitors.each |&(orig, stopping)| { + (orig.visit_item)(it, self, stopping); } } Crate(c) => { - for self.visitors.each |v| { - visit::visit_crate(c, self, *v); + for self.visitors.each |&(_, stopping)| { + visit::visit_crate(c, self, stopping); } } // Can't use visit::visit_method_helper because the @@ -449,9 +454,9 @@ impl Context { // to be a no-op, so manually invoke visit_fn. Method(m) => { let fk = visit::fk_method(copy m.ident, &m.generics, m); - for self.visitors.each |v| { - visit::visit_fn(&fk, &m.decl, &m.body, m.span, m.id, - self, *v); + for self.visitors.each |&(orig, stopping)| { + (orig.visit_fn)(&fk, &m.decl, &m.body, m.span, m.id, + self, stopping); } } } @@ -495,16 +500,16 @@ pub fn each_lint(sess: session::Session, // This is used to make the simple visitors used for the lint passes // not traverse into subitems, since that is handled by the outer // lint visitor. -fn item_stopping_visitor(v: visit::vt) -> visit::vt { +fn item_stopping_visitor(outer: visit::vt) -> visit::vt { visit::mk_vt(@visit::Visitor { visit_item: |_i, _e, _v| { }, visit_fn: |fk, fd, b, s, id, e, v| { match *fk { visit::fk_method(*) => {} - _ => visit::visit_fn(fk, fd, b, s, id, e, v) + _ => (outer.visit_fn)(fk, fd, b, s, id, e, v) } }, - .. **(ty_stopping_visitor(v))}) + .. **(ty_stopping_visitor(outer))}) } fn ty_stopping_visitor(v: visit::vt) -> visit::vt { @@ -972,68 +977,84 @@ fn lint_unnecessary_allocations() -> visit::vt<@mut Context> { }) } -fn lint_missing_struct_doc() -> visit::vt<@mut Context> { +fn lint_missing_doc() -> visit::vt<@mut Context> { + fn check_attrs(cx: @mut Context, attrs: &[ast::attribute], + sp: span, msg: &str) { + if !attrs.any(|a| a.node.is_sugared_doc) { + cx.span_lint(missing_doc, sp, msg); + } + } + visit::mk_vt(@visit::Visitor { - visit_struct_field: |field, cx: @mut Context, vt| { - let relevant = match field.node.kind { - ast::named_field(_, vis) => vis != ast::private, - ast::unnamed_field => false, - }; + visit_struct_method: |m, cx, vt| { + if m.vis == ast::public { + check_attrs(cx, m.attrs, m.span, + "missing documentation for a method"); + } + visit::visit_struct_method(m, cx, vt); + }, + + visit_ty_method: |m, cx, vt| { + // All ty_method objects are linted about because they're part of a + // trait (no visibility) + check_attrs(cx, m.attrs, m.span, + "missing documentation for a method"); + visit::visit_ty_method(m, cx, vt); + }, - if relevant { - let mut has_doc = false; - for field.node.attrs.each |attr| { - if attr.node.is_sugared_doc { - has_doc = true; - break; + visit_fn: |fk, d, b, sp, id, cx, vt| { + // Only warn about explicitly public methods. Soon implicit + // public-ness will hopefully be going away. + match *fk { + visit::fk_method(_, _, m) if m.vis == ast::public => { + // If we're in a trait implementation, no need to duplicate + // documentation + if !cx.in_trait_impl { + check_attrs(cx, m.attrs, sp, + "missing documentation for a method"); } } - if !has_doc { - cx.span_lint(missing_struct_doc, field.span, "missing documentation \ - for a field."); - } - } - visit::visit_struct_field(field, cx, vt); + _ => {} + } + visit::visit_fn(fk, d, b, sp, id, cx, vt); }, - .. *visit::default_visitor() - }) -} -fn lint_missing_trait_doc() -> visit::vt<@mut Context> { - visit::mk_vt(@visit::Visitor { - visit_trait_method: |method, cx: @mut Context, vt| { - let mut has_doc = false; - let span = match copy *method { - ast::required(m) => { - for m.attrs.each |attr| { - if attr.node.is_sugared_doc { - has_doc = true; - break; - } - } - m.span - }, - ast::provided(m) => { - if m.vis == ast::private { - has_doc = true; - } else { - for m.attrs.each |attr| { - if attr.node.is_sugared_doc { - has_doc = true; - break; + visit_item: |it, cx, vt| { + match it.node { + // Go ahead and match the fields here instead of using + // visit_struct_field while we have access to the enclosing + // struct's visibility + ast::item_struct(sdef, _) if it.vis == ast::public => { + check_attrs(cx, it.attrs, it.span, + "missing documentation for a struct"); + for sdef.fields.each |field| { + match field.node.kind { + ast::named_field(_, vis) if vis != ast::private => { + check_attrs(cx, field.node.attrs, field.span, + "missing documentation for a field"); } + ast::unnamed_field | ast::named_field(*) => {} } } - m.span } + + ast::item_trait(*) if it.vis == ast::public => { + check_attrs(cx, it.attrs, it.span, + "missing documentation for a trait"); + } + + ast::item_fn(*) if it.vis == ast::public => { + check_attrs(cx, it.attrs, it.span, + "missing documentation for a function"); + } + + _ => {} }; - if !has_doc { - cx.span_lint(missing_trait_doc, span, "missing documentation \ - for a method."); - } - visit::visit_trait_method(method, cx, vt); + + visit::visit_item(it, cx, vt); }, + .. *visit::default_visitor() }) } @@ -1045,6 +1066,7 @@ pub fn check_crate(tcx: ty::ctxt, crate: @ast::crate) { tcx: tcx, lint_stack: ~[], visitors: ~[], + in_trait_impl: false, }; // Install defaults. @@ -1066,8 +1088,7 @@ pub fn check_crate(tcx: ty::ctxt, crate: @ast::crate) { cx.add_lint(lint_unused_mut()); cx.add_lint(lint_session()); cx.add_lint(lint_unnecessary_allocations()); - cx.add_lint(lint_missing_struct_doc()); - cx.add_lint(lint_missing_trait_doc()); + cx.add_lint(lint_missing_doc()); // Actually perform the lint checks (iterating the ast) do cx.with_lint_attrs(crate.node.attrs) { @@ -1076,6 +1097,12 @@ pub fn check_crate(tcx: ty::ctxt, crate: @ast::crate) { visit::visit_crate(crate, cx, visit::mk_vt(@visit::Visitor { visit_item: |it, cx: @mut Context, vt| { do cx.with_lint_attrs(it.attrs) { + match it.node { + ast::item_impl(_, Some(*), _, _) => { + cx.in_trait_impl = true; + } + _ => {} + } check_item_ctypes(cx, it); check_item_non_camel_case_types(cx, it); check_item_default_methods(cx, it); @@ -1083,6 +1110,7 @@ pub fn check_crate(tcx: ty::ctxt, crate: @ast::crate) { cx.process(Item(it)); visit::visit_item(it, cx, vt); + cx.in_trait_impl = false; } }, visit_fn: |fk, decl, body, span, id, cx, vt| { diff --git a/src/test/compile-fail/lint-missing-doc.rs b/src/test/compile-fail/lint-missing-doc.rs new file mode 100644 index 0000000000000..fd0b0fb80f817 --- /dev/null +++ b/src/test/compile-fail/lint-missing-doc.rs @@ -0,0 +1,72 @@ +// Copyright 2013 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +// When denying at the crate level, be sure to not get random warnings from the +// injected intrinsics by the compiler. +#[deny(missing_doc)]; + +struct Foo { + a: int, + priv b: int, + pub c: int, // doesn't matter, Foo is private +} + +pub struct PubFoo { //~ ERROR: missing documentation + a: int, //~ ERROR: missing documentation + priv b: int, + pub c: int, //~ ERROR: missing documentation +} + +#[allow(missing_doc)] +pub struct PubFoo2 { + a: int, + pub c: int, +} + +/// dox +pub fn foo() {} +pub fn foo2() {} //~ ERROR: missing documentation +fn foo3() {} +#[allow(missing_doc)] pub fn foo4() {} + +/// dox +pub trait A {} +trait B {} +pub trait C {} //~ ERROR: missing documentation +#[allow(missing_doc)] pub trait D {} + +trait Bar { + /// dox + pub fn foo(); + fn foo2(); //~ ERROR: missing documentation + pub fn foo3(); //~ ERROR: missing documentation +} + +impl Foo { + pub fn foo() {} //~ ERROR: missing documentation + /// dox + pub fn foo1() {} + fn foo2() {} + #[allow(missing_doc)] pub fn foo3() {} +} + +#[allow(missing_doc)] +trait F { + pub fn a(); + fn b(&self); +} + +// should need to redefine documentation for implementations of traits +impl F for Foo { + pub fn a() {} + fn b(&self) {} +} + +fn main() {} From 4a5d887b58ff9833a968e7a0d28282b915e01de8 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 28 May 2013 16:53:43 -0500 Subject: [PATCH 2/4] Allow doc(hidden) and --test to disable doc linting --- src/librustc/middle/lint.rs | 39 +++++++++++++++++++++-- src/test/compile-fail/lint-missing-doc.rs | 13 ++++++++ 2 files changed, 49 insertions(+), 3 deletions(-) diff --git a/src/librustc/middle/lint.rs b/src/librustc/middle/lint.rs index c42c8b8bb8477..6dd911e8ef321 100644 --- a/src/librustc/middle/lint.rs +++ b/src/librustc/middle/lint.rs @@ -297,6 +297,10 @@ struct Context { // Just a simple flag if we're currently recursing into a trait // implementation. This is only used by the lint_missing_doc() pass in_trait_impl: bool, + // Another flag for doc lint emissions. Does some parent of the current node + // have the doc(hidden) attribute? Treating this as allow(missing_doc) would + // play badly with forbid(missing_doc) when it shouldn't. + doc_hidden: bool, // When recursing into an attributed node of the ast which modifies lint // levels, this stack keeps track of the previous lint levels of whatever // was modified. @@ -422,9 +426,30 @@ impl Context { } } + // detect doc(hidden) + let mut doc_hidden = false; + for attr::find_attrs_by_name(attrs, "doc").each |attr| { + match attr::get_meta_item_list(attr.node.value) { + Some(s) => { + if attr::find_meta_items_by_name(s, "hidden").len() > 0 { + doc_hidden = true; + } + } + None => {} + } + } + if doc_hidden && !self.doc_hidden { + self.doc_hidden = true; + } else { + doc_hidden = false; + } + f(); // rollback + if doc_hidden && self.doc_hidden { + self.doc_hidden = false; + } for pushed.times { let (lint, lvl, src) = self.lint_stack.pop(); self.set_level(lint, lvl, src); @@ -980,9 +1005,16 @@ fn lint_unnecessary_allocations() -> visit::vt<@mut Context> { fn lint_missing_doc() -> visit::vt<@mut Context> { fn check_attrs(cx: @mut Context, attrs: &[ast::attribute], sp: span, msg: &str) { - if !attrs.any(|a| a.node.is_sugared_doc) { - cx.span_lint(missing_doc, sp, msg); - } + // If we're building a test harness, then warning about documentation is + // probably not really relevant right now + if cx.tcx.sess.opts.test { return } + // If we have doc(hidden), nothing to do + if cx.doc_hidden { return } + // If we're documented, nothing to do + if attrs.any(|a| a.node.is_sugared_doc) { return } + + // otherwise, warn! + cx.span_lint(missing_doc, sp, msg); } visit::mk_vt(@visit::Visitor { @@ -1067,6 +1099,7 @@ pub fn check_crate(tcx: ty::ctxt, crate: @ast::crate) { lint_stack: ~[], visitors: ~[], in_trait_impl: false, + doc_hidden: false, }; // Install defaults. diff --git a/src/test/compile-fail/lint-missing-doc.rs b/src/test/compile-fail/lint-missing-doc.rs index fd0b0fb80f817..2350ca68b9747 100644 --- a/src/test/compile-fail/lint-missing-doc.rs +++ b/src/test/compile-fail/lint-missing-doc.rs @@ -69,4 +69,17 @@ impl F for Foo { fn b(&self) {} } +// It sure is nice if doc(hidden) implies allow(missing_doc), and that it +// applies recursively +#[doc(hidden)] +mod a { + pub fn baz() {} + pub mod b { + pub fn baz() {} + } +} + +#[doc(hidden)] +pub fn baz() {} + fn main() {} From 007651cd267ee8af88384d968183a1dee0265919 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 28 May 2013 16:35:52 -0500 Subject: [PATCH 3/4] Require documentation by default for libstd Adds documentation for various things that I understand. Adds #[allow(missing_doc)] for lots of things that I don't understand. --- src/libstd/at_vec.rs | 10 +- src/libstd/cast.rs | 2 + src/libstd/cell.rs | 2 + src/libstd/char.rs | 5 + src/libstd/clone.rs | 3 + src/libstd/cmp.rs | 2 + src/libstd/comm.rs | 2 + src/libstd/condition.rs | 2 + src/libstd/container.rs | 10 +- src/libstd/core.rc | 5 +- src/libstd/from_str.rs | 4 + src/libstd/hash.rs | 2 + src/libstd/hashmap.rs | 12 + src/libstd/io.rs | 2 + src/libstd/iter.rs | 1 + src/libstd/iterator.rs | 366 ++++++++++++++++++++++++++++- src/libstd/kinds.rs | 2 + src/libstd/libc.rs | 1 + src/libstd/logging.rs | 1 + src/libstd/managed.rs | 2 + src/libstd/num/cmath.rs | 2 + src/libstd/num/f32.rs | 1 + src/libstd/num/f64.rs | 2 + src/libstd/num/float.rs | 2 + src/libstd/num/int_macros.rs | 11 + src/libstd/num/num.rs | 3 + src/libstd/num/strconv.rs | 2 + src/libstd/num/uint_macros.rs | 12 + src/libstd/old_iter.rs | 2 + src/libstd/ops.rs | 2 + src/libstd/os.rs | 30 ++- src/libstd/path.rs | 2 + src/libstd/pipes.rs | 2 + src/libstd/ptr.rs | 29 +++ src/libstd/rand.rs | 5 + src/libstd/reflect.rs | 2 + src/libstd/repr.rs | 2 + src/libstd/result.rs | 1 + src/libstd/stackwalk.rs | 2 + src/libstd/str.rs | 50 +++- src/libstd/sys.rs | 2 + src/libstd/task/local_data_priv.rs | 2 + src/libstd/task/mod.rs | 2 + src/libstd/to_bytes.rs | 4 + src/libstd/to_str.rs | 4 +- src/libstd/trie.rs | 2 + src/libstd/tuple.rs | 10 + src/libstd/unicode.rs | 2 + src/libstd/util.rs | 3 +- src/libstd/vec.rs | 137 +++++++---- 50 files changed, 699 insertions(+), 69 deletions(-) diff --git a/src/libstd/at_vec.rs b/src/libstd/at_vec.rs index e3d3642d6c7e9..23f901c23ed2d 100644 --- a/src/libstd/at_vec.rs +++ b/src/libstd/at_vec.rs @@ -101,6 +101,9 @@ pub fn build_sized_opt(size: Option, } // Appending + +/// Iterates over the `rhs` vector, copying each element and appending it to the +/// `lhs`. Afterwards, the `lhs` is then returned for use again. #[inline(always)] pub fn append(lhs: @[T], rhs: &const [T]) -> @[T] { do build_sized(lhs.len() + rhs.len()) |push| { @@ -211,6 +214,9 @@ pub mod raw { (**repr).unboxed.fill = new_len * sys::size_of::(); } + /** + * Pushes a new value onto this vector. + */ #[inline(always)] pub unsafe fn push(v: &mut @[T], initval: T) { let repr: **VecRepr = transmute_copy(&v); @@ -223,7 +229,7 @@ pub mod raw { } #[inline(always)] // really pretty please - pub unsafe fn push_fast(v: &mut @[T], initval: T) { + unsafe fn push_fast(v: &mut @[T], initval: T) { let repr: **mut VecRepr = ::cast::transmute(v); let fill = (**repr).unboxed.fill; (**repr).unboxed.fill += sys::size_of::(); @@ -232,7 +238,7 @@ pub mod raw { move_val_init(&mut(*p), initval); } - pub unsafe fn push_slow(v: &mut @[T], initval: T) { + unsafe fn push_slow(v: &mut @[T], initval: T) { reserve_at_least(&mut *v, v.len() + 1u); push_fast(v, initval); } diff --git a/src/libstd/cast.rs b/src/libstd/cast.rs index 30ad41f0ca2a9..2109568a0a4e0 100644 --- a/src/libstd/cast.rs +++ b/src/libstd/cast.rs @@ -27,6 +27,7 @@ pub unsafe fn transmute_copy(src: &T) -> U { dest } +/// Casts the value at `src` to U. The two types must have the same length. #[cfg(target_word_size = "32", not(stage0))] #[inline(always)] pub unsafe fn transmute_copy(src: &T) -> U { @@ -37,6 +38,7 @@ pub unsafe fn transmute_copy(src: &T) -> U { dest } +/// Casts the value at `src` to U. The two types must have the same length. #[cfg(target_word_size = "64", not(stage0))] #[inline(always)] pub unsafe fn transmute_copy(src: &T) -> U { diff --git a/src/libstd/cell.rs b/src/libstd/cell.rs index b80d3ae68f890..f6d4e966db9ea 100644 --- a/src/libstd/cell.rs +++ b/src/libstd/cell.rs @@ -23,6 +23,7 @@ Similar to a mutable option type, but friendlier. #[mutable] #[deriving(Clone, DeepClone, Eq)] +#[allow(missing_doc)] pub struct Cell { priv value: Option } @@ -32,6 +33,7 @@ pub fn Cell(value: T) -> Cell { Cell { value: Some(value) } } +/// Creates a new empty cell with no value inside. pub fn empty_cell() -> Cell { Cell { value: None } } diff --git a/src/libstd/char.rs b/src/libstd/char.rs index bd70f59212d21..073ced8988ada 100644 --- a/src/libstd/char.rs +++ b/src/libstd/char.rs @@ -53,8 +53,12 @@ use cmp::{Eq, Ord}; Cn Unassigned a reserved unassigned code point or a noncharacter */ +/// Returns whether the specified character is considered a unicode alphabetic +/// character pub fn is_alphabetic(c: char) -> bool { derived_property::Alphabetic(c) } +#[allow(missing_doc)] pub fn is_XID_start(c: char) -> bool { derived_property::XID_Start(c) } +#[allow(missing_doc)] pub fn is_XID_continue(c: char) -> bool { derived_property::XID_Continue(c) } /// @@ -256,6 +260,7 @@ pub fn len_utf8_bytes(c: char) -> uint { ) } +#[allow(missing_doc)] pub trait Char { fn is_alphabetic(&self) -> bool; fn is_XID_start(&self) -> bool; diff --git a/src/libstd/clone.rs b/src/libstd/clone.rs index 2965b31a8c390..f74d9abda8b28 100644 --- a/src/libstd/clone.rs +++ b/src/libstd/clone.rs @@ -24,6 +24,7 @@ by convention implementing the `Clone` trait and calling the use core::kinds::Const; +/// A common trait for cloning an object. pub trait Clone { /// Returns a copy of the value. The contents of owned pointers /// are copied to maintain uniqueness, while the contents of @@ -85,6 +86,8 @@ clone_impl!(()) clone_impl!(bool) clone_impl!(char) +/// A trait distinct from `Clone` which represents "deep copies" of things like +/// managed boxes which would otherwise not be copied. pub trait DeepClone { /// Return a deep copy of the value. Unlike `Clone`, the contents of shared pointer types /// *are* copied. Note that this is currently unimplemented for managed boxes, as diff --git a/src/libstd/cmp.rs b/src/libstd/cmp.rs index ca9c49b2c0682..55530f181a11b 100644 --- a/src/libstd/cmp.rs +++ b/src/libstd/cmp.rs @@ -20,6 +20,8 @@ and `Eq` to overload the `==` and `!=` operators. */ +#[allow(missing_doc)]; + /** * Trait for values that can be compared for equality and inequality. * diff --git a/src/libstd/comm.rs b/src/libstd/comm.rs index adc2c21580b02..e044a73b338fe 100644 --- a/src/libstd/comm.rs +++ b/src/libstd/comm.rs @@ -12,6 +12,8 @@ Message passing */ +#[allow(missing_doc)]; + use cast::{transmute, transmute_mut}; use container::Container; use either::{Either, Left, Right}; diff --git a/src/libstd/condition.rs b/src/libstd/condition.rs index 94b32b6af4c77..eed61aab5c0bc 100644 --- a/src/libstd/condition.rs +++ b/src/libstd/condition.rs @@ -10,6 +10,8 @@ /*! Condition handling */ +#[allow(missing_doc)]; + use local_data::{local_data_pop, local_data_set}; use local_data; use prelude::*; diff --git a/src/libstd/container.rs b/src/libstd/container.rs index 505aa5881c5c2..065582e2e0d2e 100644 --- a/src/libstd/container.rs +++ b/src/libstd/container.rs @@ -12,6 +12,8 @@ use option::Option; +/// A trait to represent the abstract idea of a container. The only concrete +/// knowledge known is the number of elements contained within. pub trait Container { /// Return the number of elements in the container fn len(&const self) -> uint; @@ -20,16 +22,19 @@ pub trait Container { fn is_empty(&const self) -> bool; } +/// A trait to represent mutable containers pub trait Mutable: Container { /// Clear the container, removing all values. fn clear(&mut self); } +/// A map is a key-value store where values may be looked up by their keys. This +/// trait provides basic operations to operate on these stores. pub trait Map: Mutable { /// Return true if the map contains a value for the specified key fn contains_key(&self, key: &K) -> bool; - // Visits all keys and values + /// Visits all keys and values fn each<'a>(&'a self, f: &fn(&K, &'a V) -> bool) -> bool; /// Visit all keys @@ -65,6 +70,9 @@ pub trait Map: Mutable { fn pop(&mut self, k: &K) -> Option; } +/// A set is a group of objects which are each distinct from one another. This +/// trait represents actions which can be performed on sets to manipulate and +/// iterate over them. pub trait Set: Mutable { /// Return true if the set contains a value fn contains(&self, value: &T) -> bool; diff --git a/src/libstd/core.rc b/src/libstd/core.rc index 85397cbe77799..82e0d4b54d281 100644 --- a/src/libstd/core.rc +++ b/src/libstd/core.rc @@ -56,12 +56,15 @@ they contained the following prologue: #[license = "MIT/ASL2"]; #[crate_type = "lib"]; +// NOTE: remove these two attributes after the next snapshot +#[no_core]; // for stage0 +#[allow(unrecognized_lint)]; // otherwise stage0 is seriously ugly // Don't link to std. We are std. -#[no_core]; // for stage0 #[no_std]; #[deny(non_camel_case_types)]; +#[deny(missing_doc)]; // Make core testable by not duplicating lang items. See #2912 #[cfg(test)] extern mod realstd(name = "std"); diff --git a/src/libstd/from_str.rs b/src/libstd/from_str.rs index ebf6d212466a5..d2f1a895e1e2b 100644 --- a/src/libstd/from_str.rs +++ b/src/libstd/from_str.rs @@ -12,6 +12,10 @@ use option::Option; +/// A trait to abstract the idea of creating a new instance of a type from a +/// string. pub trait FromStr { + /// Parses a string `s` to return an optional value of this type. If the + /// string is ill-formatted, the None is returned. fn from_str(s: &str) -> Option; } diff --git a/src/libstd/hash.rs b/src/libstd/hash.rs index 9828ff4e31742..e902244578634 100644 --- a/src/libstd/hash.rs +++ b/src/libstd/hash.rs @@ -19,6 +19,8 @@ * CPRNG like rand::rng. */ +#[allow(missing_doc)]; + use container::Container; use old_iter::BaseIter; use rt::io::Writer; diff --git a/src/libstd/hashmap.rs b/src/libstd/hashmap.rs index e6ccb7a1d6b23..72f92bc1522e9 100644 --- a/src/libstd/hashmap.rs +++ b/src/libstd/hashmap.rs @@ -34,6 +34,14 @@ struct Bucket { value: V, } +/// A hash map implementation which uses linear probing along with the SipHash +/// hash function for internal state. This means that the order of all hash maps +/// is randomized by keying each hash map randomly on creation. +/// +/// It is required that the keys implement the `Eq` and `Hash` traits, although +/// this can frequently be achieved by just implementing the `Eq` and +/// `IterBytes` traits as `Hash` is automatically implemented for types that +/// implement `IterBytes`. pub struct HashMap { priv k0: u64, priv k1: u64, @@ -53,6 +61,7 @@ fn resize_at(capacity: uint) -> uint { ((capacity as float) * 3. / 4.) as uint } +/// Creates a new hash map with the specified capacity. pub fn linear_map_with_capacity( initial_capacity: uint) -> HashMap { let mut r = rand::task_rng(); @@ -539,6 +548,9 @@ impl Eq for HashMap { fn ne(&self, other: &HashMap) -> bool { !self.eq(other) } } +/// An implementation of a hash set using the underlying representation of a +/// HashMap where the value is (). As with the `HashMap` type, a `HashSet` +/// requires that the elements implement the `Eq` and `Hash` traits. pub struct HashSet { priv map: HashMap } diff --git a/src/libstd/io.rs b/src/libstd/io.rs index b97b0c70afcc9..011c56ac7c14a 100644 --- a/src/libstd/io.rs +++ b/src/libstd/io.rs @@ -44,6 +44,8 @@ implement `Reader` and `Writer`, where appropriate. */ +#[allow(missing_doc)]; + use result::Result; use container::Container; diff --git a/src/libstd/iter.rs b/src/libstd/iter.rs index 5847034d02601..e5d79d79fcef3 100644 --- a/src/libstd/iter.rs +++ b/src/libstd/iter.rs @@ -46,6 +46,7 @@ use vec::OwnedVector; use num::{One, Zero}; use ops::{Add, Mul}; +#[allow(missing_doc)] pub trait Times { fn times(&self, it: &fn() -> bool) -> bool; } diff --git a/src/libstd/iterator.rs b/src/libstd/iterator.rs index 69bb1b0b766cf..b13c4ca23e6cc 100644 --- a/src/libstd/iterator.rs +++ b/src/libstd/iterator.rs @@ -23,6 +23,9 @@ use num::{Zero, One}; use num; use prelude::*; +/// An interface for dealing with "external iterators". These types of iterators +/// can be resumed at any time as all state is stored internally as opposed to +/// being located on the call stack. pub trait Iterator { /// Advance the iterator and return the next value. Return `None` when the end is reached. fn next(&mut self) -> Option; @@ -33,26 +36,307 @@ pub trait Iterator { /// /// In the future these will be default methods instead of a utility trait. pub trait IteratorUtil { + /// Chan this iterator with another, returning a new iterator which will + /// finish iterating over the current iterator, and then it will iterate + /// over the other specified iterator. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [0]; + /// let b = [1]; + /// let mut it = a.iter().chain(b.iter()); + /// assert_eq!(it.next().get(), &0); + /// assert_eq!(it.next().get(), &1); + /// assert!(it.next().is_none()); + /// ~~~ fn chain>(self, other: U) -> ChainIterator; + + /// Creates an iterator which iterates over both this and the specified + /// iterators simultaneously, yielding the two elements as pairs. When + /// either iterator returns None, all further invocations of next() will + /// return None. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [0]; + /// let b = [1]; + /// let mut it = a.iter().zip(b.iter()); + /// assert_eq!(it.next().get(), (&0, &1)); + /// assert!(it.next().is_none()); + /// ~~~ fn zip>(self, other: U) -> ZipIterator; + // FIXME: #5898: should be called map + /// Creates a new iterator which will apply the specified function to each + /// element returned by the first, yielding the mapped element instead. This + /// similar to the `vec::map` function. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2]; + /// let mut it = a.iter().transform(|&x| 2 * x); + /// assert_eq!(it.next().get(), 2); + /// assert_eq!(it.next().get(), 4); + /// assert!(it.next().is_none()); + /// ~~~ fn transform<'r, B>(self, f: &'r fn(A) -> B) -> MapIterator<'r, A, B, Self>; + + /// Creates an iterator which applies the predicate to each element returned + /// by this iterator. Only elements which have the predicate evaluate to + /// `true` will be yielded. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2]; + /// let mut it = a.iter().filter(|&x| *x > 1); + /// assert_eq!(it.next().get(), &2); + /// assert!(it.next().is_none()); + /// ~~~ fn filter<'r>(self, predicate: &'r fn(&A) -> bool) -> FilterIterator<'r, A, Self>; + + /// Creates an iterator which both filters and maps elements at the same + /// If the specified function returns None, the element is skipped. + /// Otherwise the option is unwrapped and the new value is yielded. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2]; + /// let mut it = a.iter().filter_map(|&x| if x > 1 {Some(2 * x)} else {None}); + /// assert_eq!(it.next().get(), 4); + /// assert!(it.next().is_none()); + /// ~~~ fn filter_map<'r, B>(self, f: &'r fn(A) -> Option) -> FilterMapIterator<'r, A, B, Self>; + + /// Creates an iterator which yields a pair of the value returned by this + /// iterator plus the current index of iteration. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [100, 200]; + /// let mut it = a.iter().enumerate(); + /// assert_eq!(it.next().get(), (0, &100)); + /// assert_eq!(it.next().get(), (1, &200)); + /// assert!(it.next().is_none()); + /// ~~~ fn enumerate(self) -> EnumerateIterator; + + /// Creates an iterator which invokes the predicate on elements until it + /// returns true. Once the predicate returns true, all further elements are + /// yielded. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 2, 1]; + /// let mut it = a.iter().skip_while(|&a| *a < 3); + /// assert_eq!(it.next().get(), &3); + /// assert_eq!(it.next().get(), &2); + /// assert_eq!(it.next().get(), &1); + /// assert!(it.next().is_none()); + /// ~~~ fn skip_while<'r>(self, predicate: &'r fn(&A) -> bool) -> SkipWhileIterator<'r, A, Self>; + + /// Creates an iterator which yields elements so long as the predicate + /// returns true. After the predicate returns false for the first time, no + /// further elements will be yielded. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 2, 1]; + /// let mut it = a.iter().take_while(|&a| *a < 3); + /// assert_eq!(it.next().get(), &1); + /// assert_eq!(it.next().get(), &2); + /// assert!(it.next().is_none()); + /// ~~~ fn take_while<'r>(self, predicate: &'r fn(&A) -> bool) -> TakeWhileIterator<'r, A, Self>; + + /// Creates an iterator which skips the first `n` elements of this iterator, + /// and then it yields all further items. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// let mut it = a.iter().skip(3); + /// assert_eq!(it.next().get(), &4); + /// assert_eq!(it.next().get(), &5); + /// assert!(it.next().is_none()); + /// ~~~ fn skip(self, n: uint) -> SkipIterator; + + /// Creates an iterator which yields the first `n` elements of this + /// iterator, and then it will always return None. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// let mut it = a.iter().take(3); + /// assert_eq!(it.next().get(), &1); + /// assert_eq!(it.next().get(), &2); + /// assert_eq!(it.next().get(), &3); + /// assert!(it.next().is_none()); + /// ~~~ fn take(self, n: uint) -> TakeIterator; + + /// Creates a new iterator which behaves in a similar fashion to foldl. + /// There is a state which is passed between each iteration and can be + /// mutated as necessary. The yielded values from the closure are yielded + /// from the ScanIterator instance when not None. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// let mut it = a.iter().scan(1, |fac, &x| { + /// *fac = *fac * x; + /// Some(*fac) + /// }); + /// assert_eq!(it.next().get(), 1); + /// assert_eq!(it.next().get(), 2); + /// assert_eq!(it.next().get(), 6); + /// assert_eq!(it.next().get(), 24); + /// assert_eq!(it.next().get(), 120); + /// assert!(it.next().is_none()); + /// ~~~ fn scan<'r, St, B>(self, initial_state: St, f: &'r fn(&mut St, A) -> Option) -> ScanIterator<'r, A, B, Self, St>; + + /// An adaptation of an external iterator to the for-loop protocol of rust. + /// + /// # Example + /// + /// ~~~ {.rust} + /// for Counter::new(0, 10).advance |i| { + /// io::println(fmt!("%d", i)); + /// } + /// ~~~ fn advance(&mut self, f: &fn(A) -> bool) -> bool; + + /// Loops through the entire iterator, accumulating all of the elements into + /// a vector. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// let b = a.iter().transform(|&x| x).to_vec(); + /// assert!(a == b); + /// ~~~ fn to_vec(&mut self) -> ~[A]; + + /// Loops through `n` iterations, returning the `n`th element of the + /// iterator. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// let mut it = a.iter(); + /// assert!(it.nth(2).get() == &3); + /// assert!(it.nth(2) == None); + /// ~~~ fn nth(&mut self, n: uint) -> Option; + + /// Loops through the entire iterator, returning the last element of the + /// iterator. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// assert!(a.iter().last().get() == &5); + /// ~~~ fn last(&mut self) -> Option; + + /// Performs a fold operation over the entire iterator, returning the + /// eventual state at the end of the iteration. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// assert!(a.iter().fold(0, |a, &b| a + b) == 15); + /// ~~~ fn fold(&mut self, start: B, f: &fn(B, A) -> B) -> B; + + /// Counts the number of elements in this iterator. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// let mut it = a.iter(); + /// assert!(it.count() == 5); + /// assert!(it.count() == 0); + /// ~~~ fn count(&mut self) -> uint; + + /// Tests whether the predicate holds true for all elements in the iterator. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// assert!(a.iter().all(|&x| *x > 0)); + /// assert!(!a.iter().all(|&x| *x > 2)); + /// ~~~ fn all(&mut self, f: &fn(&A) -> bool) -> bool; + + /// Tests whether any element of an iterator satisfies the specified + /// predicate. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// let mut it = a.iter(); + /// assert!(it.any(|&x| *x == 3)); + /// assert!(!it.any(|&x| *x == 3)); + /// ~~~ fn any(&mut self, f: &fn(&A) -> bool) -> bool; } @@ -186,7 +470,19 @@ impl> IteratorUtil for T { } } +/// A trait for iterators over elements which can be added together pub trait AdditiveIterator { + /// Iterates over the entire iterator, summing up all the elements + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// let mut it = a.iter().transform(|&x| x); + /// assert!(it.sum() == 15); + /// ~~~ fn sum(&mut self) -> A; } @@ -195,7 +491,23 @@ impl + Zero, T: Iterator> AdditiveIterator for T { fn sum(&mut self) -> A { self.fold(Zero::zero::(), |s, x| s + x) } } +/// A trait for iterators over elements whose elements can be multiplied +/// together. pub trait MultiplicativeIterator { + /// Iterates over the entire iterator, multiplying all the elements + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// fn factorial(n: uint) -> uint { + /// Counter::new(1u, 1).take_while(|&i| i <= n).product() + /// } + /// assert!(factorial(0) == 1); + /// assert!(factorial(1) == 1); + /// assert!(factorial(5) == 120); + /// ~~~ fn product(&mut self) -> A; } @@ -204,8 +516,31 @@ impl + One, T: Iterator> MultiplicativeIterator for T { fn product(&mut self) -> A { self.fold(One::one::(), |p, x| p * x) } } +/// A trait for iterators over elements which can be compared to one another. +/// The type of each element must ascribe to the `Ord` trait. pub trait OrdIterator { + /// Consumes the entire iterator to return the maximum element. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// assert!(a.iter().max().get() == &5); + /// ~~~ fn max(&mut self) -> Option; + + /// Consumes the entire iterator to return the minimum element. + /// + /// # Example + /// + /// ~~~ {.rust} + /// use std::iterator::*; + /// + /// let a = [1, 2, 3, 4, 5]; + /// assert!(a.iter().min().get() == &1); + /// ~~~ fn min(&mut self) -> Option; } @@ -231,6 +566,7 @@ impl> OrdIterator for T { } } +/// An iterator which strings two iterators together pub struct ChainIterator { priv a: T, priv b: U, @@ -253,6 +589,7 @@ impl, U: Iterator> Iterator for ChainIterator { } } +/// An iterator which iterates two other iterators simultaneously pub struct ZipIterator { priv a: T, priv b: U @@ -268,6 +605,7 @@ impl, U: Iterator> Iterator<(A, B)> for ZipIterator { priv iter: T, priv f: &'self fn(A) -> B @@ -283,6 +621,7 @@ impl<'self, A, B, T: Iterator> Iterator for MapIterator<'self, A, B, T> { } } +/// An iterator which filters the elements of `iter` with `predicate` pub struct FilterIterator<'self, A, T> { priv iter: T, priv predicate: &'self fn(&A) -> bool @@ -302,6 +641,7 @@ impl<'self, A, T: Iterator> Iterator for FilterIterator<'self, A, T> { } } +/// An iterator which uses `f` to both filter and map elements from `iter` pub struct FilterMapIterator<'self, A, B, T> { priv iter: T, priv f: &'self fn(A) -> Option @@ -320,6 +660,7 @@ impl<'self, A, B, T: Iterator> Iterator for FilterMapIterator<'self, A, B, } } +/// An iterator which yields the current count and the element during iteration pub struct EnumerateIterator { priv iter: T, priv count: uint @@ -339,6 +680,7 @@ impl> Iterator<(uint, A)> for EnumerateIterator { } } +/// An iterator which rejects elements while `predicate` is true pub struct SkipWhileIterator<'self, A, T> { priv iter: T, priv flag: bool, @@ -370,6 +712,7 @@ impl<'self, A, T: Iterator> Iterator for SkipWhileIterator<'self, A, T> { } } +/// An iterator which only accepts elements while `predicate` is true pub struct TakeWhileIterator<'self, A, T> { priv iter: T, priv flag: bool, @@ -397,6 +740,7 @@ impl<'self, A, T: Iterator> Iterator for TakeWhileIterator<'self, A, T> { } } +/// An iterator which skips over `n` elements of `iter` pub struct SkipIterator { priv iter: T, priv n: uint @@ -428,6 +772,7 @@ impl> Iterator for SkipIterator { } } +/// An iterator which only iterates over the first `n` iterations of `iter`. pub struct TakeIterator { priv iter: T, priv n: uint @@ -446,9 +791,12 @@ impl> Iterator for TakeIterator { } } +/// An iterator to maintain state while iterating another iterator pub struct ScanIterator<'self, A, B, T, St> { priv iter: T, priv f: &'self fn(&mut St, A) -> Option, + + /// The current internal state to be passed to the closure next. state: St } @@ -459,14 +807,18 @@ impl<'self, A, B, T: Iterator, St> Iterator for ScanIterator<'self, A, B, } } +/// An iterator which just modifies the contained state throughout iteration. pub struct UnfoldrIterator<'self, A, St> { priv f: &'self fn(&mut St) -> Option, + /// Internal state that will be yielded on the next iteration state: St } -pub impl<'self, A, St> UnfoldrIterator<'self, A, St> { +impl<'self, A, St> UnfoldrIterator<'self, A, St> { + /// Creates a new iterator with the specified closure as the "iterator + /// function" and an initial state to eventually pass to the iterator #[inline] - fn new(f: &'self fn(&mut St) -> Option, initial_state: St) + pub fn new(f: &'self fn(&mut St) -> Option, initial_state: St) -> UnfoldrIterator<'self, A, St> { UnfoldrIterator { f: f, @@ -482,15 +834,19 @@ impl<'self, A, St> Iterator for UnfoldrIterator<'self, A, St> { } } -/// An infinite iterator starting at `start` and advancing by `step` with each iteration +/// An infinite iterator starting at `start` and advancing by `step` with each +/// iteration pub struct Counter { + /// The current state the counter is at (next value to be yielded) state: A, + /// The amount that this iterator is stepping by step: A } -pub impl Counter { +impl Counter { + /// Creates a new counter with the specified start/step #[inline(always)] - fn new(start: A, step: A) -> Counter { + pub fn new(start: A, step: A) -> Counter { Counter{state: start, step: step} } } diff --git a/src/libstd/kinds.rs b/src/libstd/kinds.rs index d9b3e35b6b9d7..b6c22f29c3e5a 100644 --- a/src/libstd/kinds.rs +++ b/src/libstd/kinds.rs @@ -37,6 +37,8 @@ instead implement `Clone`. */ +#[allow(missing_doc)]; + #[lang="copy"] pub trait Copy { // Empty. diff --git a/src/libstd/libc.rs b/src/libstd/libc.rs index 7ae3f0fd2d462..142b2f7d6af58 100644 --- a/src/libstd/libc.rs +++ b/src/libstd/libc.rs @@ -64,6 +64,7 @@ */ #[allow(non_camel_case_types)]; +#[allow(missing_doc)]; // Initial glob-exports mean that all the contents of all the modules // wind up exported, if you're interested in writing platform-specific code. diff --git a/src/libstd/logging.rs b/src/libstd/logging.rs index 693d786329773..c2f854179b8dd 100644 --- a/src/libstd/logging.rs +++ b/src/libstd/logging.rs @@ -36,6 +36,7 @@ pub fn console_off() { #[cfg(not(test))] #[lang="log_type"] +#[allow(missing_doc)] pub fn log_type(level: u32, object: &T) { use cast; use container::Container; diff --git a/src/libstd/managed.rs b/src/libstd/managed.rs index ecde1eb19179d..fb6ac7603ca76 100644 --- a/src/libstd/managed.rs +++ b/src/libstd/managed.rs @@ -21,6 +21,7 @@ pub mod raw { pub static RC_MANAGED_UNIQUE : uint = (-2) as uint; pub static RC_IMMORTAL : uint = 0x77777777; + #[allow(missing_doc)] pub struct BoxHeaderRepr { ref_count: uint, type_desc: *TyDesc, @@ -28,6 +29,7 @@ pub mod raw { next: *BoxRepr, } + #[allow(missing_doc)] pub struct BoxRepr { header: BoxHeaderRepr, data: u8 diff --git a/src/libstd/num/cmath.rs b/src/libstd/num/cmath.rs index 9626224916bbb..96d3b79e33850 100644 --- a/src/libstd/num/cmath.rs +++ b/src/libstd/num/cmath.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + // function names are almost identical to C's libmath, a few have been // renamed, grep for "rename:" diff --git a/src/libstd/num/f32.rs b/src/libstd/num/f32.rs index 64737c47f295d..62ce5ed65e10c 100644 --- a/src/libstd/num/f32.rs +++ b/src/libstd/num/f32.rs @@ -9,6 +9,7 @@ // except according to those terms. //! Operations and constants for `f32` +#[allow(missing_doc)]; use libc::c_int; use num::{Zero, One, strconv}; diff --git a/src/libstd/num/f64.rs b/src/libstd/num/f64.rs index f01d45bbd1db4..de44d861645b3 100644 --- a/src/libstd/num/f64.rs +++ b/src/libstd/num/f64.rs @@ -10,6 +10,8 @@ //! Operations and constants for `f64` +#[allow(missing_doc)]; + use libc::c_int; use num::{Zero, One, strconv}; use num::{FPCategory, FPNaN, FPInfinite , FPZero, FPSubnormal, FPNormal}; diff --git a/src/libstd/num/float.rs b/src/libstd/num/float.rs index 30de95b484669..97d661d8fe2e7 100644 --- a/src/libstd/num/float.rs +++ b/src/libstd/num/float.rs @@ -20,6 +20,8 @@ // PORT this must match in width according to architecture +#[allow(missing_doc)]; + use f64; use libc::c_int; use num::{Zero, One, strconv}; diff --git a/src/libstd/num/int_macros.rs b/src/libstd/num/int_macros.rs index 778e741ff3be3..023f44c433c00 100644 --- a/src/libstd/num/int_macros.rs +++ b/src/libstd/num/int_macros.rs @@ -26,12 +26,17 @@ pub static bytes : uint = ($bits / 8); pub static min_value: $T = (-1 as $T) << (bits - 1); pub static max_value: $T = min_value - 1 as $T; +/// Calculates the sum of two numbers #[inline(always)] pub fn add(x: $T, y: $T) -> $T { x + y } +/// Subtracts the second number from the first #[inline(always)] pub fn sub(x: $T, y: $T) -> $T { x - y } +/// Multiplies two numbers together #[inline(always)] pub fn mul(x: $T, y: $T) -> $T { x * y } +/// Divides the first argument by the second argument (using integer division) +/// Divides the first argument by the second argument (using integer division) #[inline(always)] pub fn div(x: $T, y: $T) -> $T { x / y } @@ -58,16 +63,22 @@ pub fn div(x: $T, y: $T) -> $T { x / y } #[inline(always)] pub fn rem(x: $T, y: $T) -> $T { x % y } +/// Returns true iff `x < y` #[inline(always)] pub fn lt(x: $T, y: $T) -> bool { x < y } +/// Returns true iff `x <= y` #[inline(always)] pub fn le(x: $T, y: $T) -> bool { x <= y } +/// Returns true iff `x == y` #[inline(always)] pub fn eq(x: $T, y: $T) -> bool { x == y } +/// Returns true iff `x != y` #[inline(always)] pub fn ne(x: $T, y: $T) -> bool { x != y } +/// Returns true iff `x >= y` #[inline(always)] pub fn ge(x: $T, y: $T) -> bool { x >= y } +/// Returns true iff `x > y` #[inline(always)] pub fn gt(x: $T, y: $T) -> bool { x > y } diff --git a/src/libstd/num/num.rs b/src/libstd/num/num.rs index 96b302d317499..91631d3c9b904 100644 --- a/src/libstd/num/num.rs +++ b/src/libstd/num/num.rs @@ -9,6 +9,9 @@ // except according to those terms. //! An interface for numeric types + +#[allow(missing_doc)]; + use cmp::{Eq, ApproxEq, Ord}; use ops::{Add, Sub, Mul, Div, Rem, Neg}; use ops::{Not, BitAnd, BitOr, BitXor, Shl, Shr}; diff --git a/src/libstd/num/strconv.rs b/src/libstd/num/strconv.rs index 1d65b84b7cec1..30efe9a392233 100644 --- a/src/libstd/num/strconv.rs +++ b/src/libstd/num/strconv.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + use container::Container; use core::cmp::{Ord, Eq}; use ops::{Add, Sub, Mul, Div, Rem, Neg}; diff --git a/src/libstd/num/uint_macros.rs b/src/libstd/num/uint_macros.rs index f16b4f4a740b1..c2e722f9e0eb5 100644 --- a/src/libstd/num/uint_macros.rs +++ b/src/libstd/num/uint_macros.rs @@ -27,27 +27,39 @@ pub static bytes : uint = ($bits / 8); pub static min_value: $T = 0 as $T; pub static max_value: $T = 0 as $T - 1 as $T; +/// Calculates the sum of two numbers #[inline(always)] pub fn add(x: $T, y: $T) -> $T { x + y } +/// Subtracts the second number from the first #[inline(always)] pub fn sub(x: $T, y: $T) -> $T { x - y } +/// Multiplies two numbers together #[inline(always)] pub fn mul(x: $T, y: $T) -> $T { x * y } +/// Divides the first argument by the second argument (using integer division) #[inline(always)] pub fn div(x: $T, y: $T) -> $T { x / y } +/// Calculates the integer remainder when x is divided by y (equivalent to the +/// '%' operator) #[inline(always)] pub fn rem(x: $T, y: $T) -> $T { x % y } +/// Returns true iff `x < y` #[inline(always)] pub fn lt(x: $T, y: $T) -> bool { x < y } +/// Returns true iff `x <= y` #[inline(always)] pub fn le(x: $T, y: $T) -> bool { x <= y } +/// Returns true iff `x == y` #[inline(always)] pub fn eq(x: $T, y: $T) -> bool { x == y } +/// Returns true iff `x != y` #[inline(always)] pub fn ne(x: $T, y: $T) -> bool { x != y } +/// Returns true iff `x >= y` #[inline(always)] pub fn ge(x: $T, y: $T) -> bool { x >= y } +/// Returns true iff `x > y` #[inline(always)] pub fn gt(x: $T, y: $T) -> bool { x > y } diff --git a/src/libstd/old_iter.rs b/src/libstd/old_iter.rs index 389b643572cb6..22ca356fa9b18 100644 --- a/src/libstd/old_iter.rs +++ b/src/libstd/old_iter.rs @@ -14,6 +14,8 @@ */ +#[allow(missing_doc)]; + use cmp::{Eq, Ord}; use kinds::Copy; use option::{None, Option, Some}; diff --git a/src/libstd/ops.rs b/src/libstd/ops.rs index 47ff45be68726..77cfe62e49527 100644 --- a/src/libstd/ops.rs +++ b/src/libstd/ops.rs @@ -10,6 +10,8 @@ //! Traits for the built-in operators +#[allow(missing_doc)]; + #[lang="drop"] pub trait Drop { fn finalize(&self); // FIXME(#4332): Rename to "drop"? --pcwalton diff --git a/src/libstd/os.rs b/src/libstd/os.rs index c1b5c159a24cd..cc36dcb92a2d4 100644 --- a/src/libstd/os.rs +++ b/src/libstd/os.rs @@ -26,6 +26,8 @@ * to write OS-ignorant code by default. */ +#[allow(missing_doc)]; + use cast; use io; use libc; @@ -45,6 +47,7 @@ use vec; pub use libc::fclose; pub use os::consts::*; +/// Delegates to the libc close() function, returning the same return value. pub fn close(fd: c_int) -> c_int { unsafe { libc::close(fd) @@ -171,6 +174,8 @@ fn with_env_lock(f: &fn() -> T) -> T { } } +/// Returns a vector of (variable, value) pairs for all the environment +/// variables of the current process. pub fn env() -> ~[(~str,~str)] { unsafe { #[cfg(windows)] @@ -236,6 +241,8 @@ pub fn env() -> ~[(~str,~str)] { } #[cfg(unix)] +/// Fetches the environment variable `n` from the current process, returning +/// None if the variable isn't set. pub fn getenv(n: &str) -> Option<~str> { unsafe { do with_env_lock { @@ -251,6 +258,8 @@ pub fn getenv(n: &str) -> Option<~str> { } #[cfg(windows)] +/// Fetches the environment variable `n` from the current process, returning +/// None if the variable isn't set. pub fn getenv(n: &str) -> Option<~str> { unsafe { do with_env_lock { @@ -266,6 +275,8 @@ pub fn getenv(n: &str) -> Option<~str> { #[cfg(unix)] +/// Sets the environment variable `n` to the value `v` for the currently running +/// process pub fn setenv(n: &str, v: &str) { unsafe { do with_env_lock { @@ -280,6 +291,8 @@ pub fn setenv(n: &str, v: &str) { #[cfg(windows)] +/// Sets the environment variable `n` to the value `v` for the currently running +/// process pub fn setenv(n: &str, v: &str) { unsafe { do with_env_lock { @@ -422,13 +435,14 @@ fn dup2(src: c_int, dst: c_int) -> c_int { } } - +/// Returns the proper dll filename for the given basename of a file. pub fn dll_filename(base: &str) -> ~str { return str::to_owned(DLL_PREFIX) + str::to_owned(base) + str::to_owned(DLL_SUFFIX) } - +/// Optionally returns the filesystem path to the current executable which is +/// running. If any failure occurs, None is returned. pub fn self_exe_path() -> Option { #[cfg(target_os = "freebsd")] @@ -828,6 +842,8 @@ pub fn remove_dir(p: &Path) -> bool { } } +/// Changes the current working directory to the specified path, returning +/// whether the change was completed successfully or not. pub fn change_dir(p: &Path) -> bool { return chdir(p); @@ -981,6 +997,7 @@ pub fn remove_file(p: &Path) -> bool { } #[cfg(unix)] +/// Returns the platform-specific value of errno pub fn errno() -> int { #[cfg(target_os = "macos")] #[cfg(target_os = "freebsd")] @@ -1012,6 +1029,7 @@ pub fn errno() -> int { } #[cfg(windows)] +/// Returns the platform-specific value of errno pub fn errno() -> uint { use libc::types::os::arch::extra::DWORD; @@ -1211,6 +1229,11 @@ struct OverriddenArgs { fn overridden_arg_key(_v: @OverriddenArgs) {} +/// Returns the arguments which this program was started with (normally passed +/// via the command line). +/// +/// The return value of the function can be changed by invoking the +/// `os::set_args` function. pub fn args() -> ~[~str] { unsafe { match local_data::local_data_get(overridden_arg_key) { @@ -1220,6 +1243,9 @@ pub fn args() -> ~[~str] { } } +/// For the current task, overrides the task-local cache of the arguments this +/// program had when it started. These new arguments are only available to the +/// current task via the `os::args` method. pub fn set_args(new_args: ~[~str]) { unsafe { let overridden_args = @OverriddenArgs { val: copy new_args }; diff --git a/src/libstd/path.rs b/src/libstd/path.rs index ed9ef864f8039..39bd57b3c3793 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -14,6 +14,8 @@ Cross-platform file path handling */ +#[allow(missing_doc)]; + use container::Container; use cmp::Eq; use libc; diff --git a/src/libstd/pipes.rs b/src/libstd/pipes.rs index 4203f87f1395b..5fbf97dccc877 100644 --- a/src/libstd/pipes.rs +++ b/src/libstd/pipes.rs @@ -82,6 +82,8 @@ bounded and unbounded protocols allows for less code duplication. */ +#[allow(missing_doc)]; + use container::Container; use cast::{forget, transmute, transmute_copy}; use either::{Either, Left, Right}; diff --git a/src/libstd/ptr.rs b/src/libstd/ptr.rs index 65375e410a67f..0f7cf3f6bdf43 100644 --- a/src/libstd/ptr.rs +++ b/src/libstd/ptr.rs @@ -120,6 +120,12 @@ pub unsafe fn copy_memory(dst: *mut T, src: *const T, count: uint) { memmove64(dst as *mut u8, src as *u8, n as u64); } +/** + * Copies data from one location to another + * + * Copies `count` elements (not bytes) from `src` to `dst`. The source + * and destination may overlap. + */ #[inline(always)] #[cfg(target_word_size = "64", not(stage0))] pub unsafe fn copy_memory(dst: *mut T, src: *const T, count: uint) { @@ -135,6 +141,13 @@ pub unsafe fn copy_nonoverlapping_memory(dst: *mut T, src: *const T, count: u memmove32(dst as *mut u8, src as *u8, n as u32); } +/** + * Copies data from one location to another. This uses memcpy instead of memmove + * to take advantage of the knowledge that the memory does not overlap. + * + * Copies `count` elements (not bytes) from `src` to `dst`. The source + * and destination may overlap. + */ #[inline(always)] #[cfg(target_word_size = "32", not(stage0))] pub unsafe fn copy_nonoverlapping_memory(dst: *mut T, src: *const T, count: uint) { @@ -150,6 +163,13 @@ pub unsafe fn copy_nonoverlapping_memory(dst: *mut T, src: *const T, count: u memmove64(dst as *mut u8, src as *u8, n as u64); } +/** + * Copies data from one location to another. This uses memcpy instead of memmove + * to take advantage of the knowledge that the memory does not overlap. + * + * Copies `count` elements (not bytes) from `src` to `dst`. The source + * and destination may overlap. + */ #[inline(always)] #[cfg(target_word_size = "64", not(stage0))] pub unsafe fn copy_nonoverlapping_memory(dst: *mut T, src: *const T, count: uint) { @@ -164,6 +184,10 @@ pub unsafe fn set_memory(dst: *mut T, c: int, count: uint) { libc_::memset(dst as *mut c_void, c as libc::c_int, n as size_t); } +/** + * Invokes memset on the specified pointer, setting `count` bytes of memory + * starting at `dst` to `c`. + */ #[inline(always)] #[cfg(target_word_size = "32", not(stage0))] pub unsafe fn set_memory(dst: *mut T, c: u8, count: uint) { @@ -171,6 +195,10 @@ pub unsafe fn set_memory(dst: *mut T, c: u8, count: uint) { memset32(dst, c, count as u32); } +/** + * Invokes memset on the specified pointer, setting `count` bytes of memory + * starting at `dst` to `c`. + */ #[inline(always)] #[cfg(target_word_size = "64", not(stage0))] pub unsafe fn set_memory(dst: *mut T, c: u8, count: uint) { @@ -268,6 +296,7 @@ pub unsafe fn array_each(arr: **T, cb: &fn(*T)) { array_each_with_len(arr, len, cb); } +#[allow(missing_doc)] pub trait Ptr { fn is_null(&const self) -> bool; fn is_not_null(&const self) -> bool; diff --git a/src/libstd/rand.rs b/src/libstd/rand.rs index 2c8681ef2883a..07a5acbdde557 100644 --- a/src/libstd/rand.rs +++ b/src/libstd/rand.rs @@ -58,6 +58,8 @@ pub mod distributions; /// A type that can be randomly generated using an Rng pub trait Rand { + /// Generates a random instance of this type using the specified source of + /// randomness fn rand(rng: &mut R) -> Self; } @@ -256,10 +258,13 @@ pub trait Rng { /// A value with a particular weight compared to other values pub struct Weighted { + /// The numerical weight of this item weight: uint, + /// The actual item which is being weighted item: T, } +/// Helper functions attached to the Rng type pub trait RngUtil { /// Return a random value of a Rand type fn gen(&mut self) -> T; diff --git a/src/libstd/reflect.rs b/src/libstd/reflect.rs index 30f60dce04113..cadfa71e7fa9c 100644 --- a/src/libstd/reflect.rs +++ b/src/libstd/reflect.rs @@ -14,6 +14,8 @@ Runtime type reflection */ +#[allow(missing_doc)]; + use intrinsic::{TyDesc, TyVisitor}; use intrinsic::Opaque; use libc::c_void; diff --git a/src/libstd/repr.rs b/src/libstd/repr.rs index a05009e375cf9..c50823f471ec1 100644 --- a/src/libstd/repr.rs +++ b/src/libstd/repr.rs @@ -14,6 +14,8 @@ More runtime type reflection */ +#[allow(missing_doc)]; + use cast::transmute; use char; use intrinsic; diff --git a/src/libstd/result.rs b/src/libstd/result.rs index cda2fe13e3766..4fe92ddb7b6fa 100644 --- a/src/libstd/result.rs +++ b/src/libstd/result.rs @@ -312,6 +312,7 @@ pub fn map_vec( } #[inline(always)] +#[allow(missing_doc)] pub fn map_opt( o_t: &Option, op: &fn(&T) -> Result) -> Result,U> { diff --git a/src/libstd/stackwalk.rs b/src/libstd/stackwalk.rs index a22599e9fc620..c3e3ca57a8e74 100644 --- a/src/libstd/stackwalk.rs +++ b/src/libstd/stackwalk.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + use cast::transmute; use unstable::intrinsics; diff --git a/src/libstd/str.rs b/src/libstd/str.rs index 349a848e2c7c3..4d41f10fdfcad 100644 --- a/src/libstd/str.rs +++ b/src/libstd/str.rs @@ -72,6 +72,16 @@ pub fn from_bytes_with_null<'a>(vv: &'a [u8]) -> &'a str { return unsafe { raw::from_bytes_with_null(vv) }; } +/** + * Converts a vector to a string slice without performing any allocations. + * + * Once the slice has been validated as utf-8, it is transmuted in-place and + * returned as a '&str' instead of a '&[u8]' + * + * # Failure + * + * Fails if invalid UTF-8 + */ pub fn from_bytes_slice<'a>(vector: &'a [u8]) -> &'a str { unsafe { assert!(is_utf8(vector)); @@ -741,6 +751,18 @@ pub fn each_split_str<'a,'b>(s: &'a str, return true; } +/** + * Splits the string `s` based on `sep`, yielding all splits to the iterator + * function provide + * + * # Example + * + * ~~~ {.rust} + * let mut v = ~[]; + * for each_split_str(".XXX.YYY.", ".") |subs| { v.push(subs); } + * assert!(v == ["XXX", "YYY"]); + * ~~~ + */ pub fn each_split_str_nonempty<'a,'b>(s: &'a str, sep: &'b str, it: &fn(&'a str) -> bool) -> bool { @@ -823,7 +845,7 @@ pub fn each_word<'a>(s: &'a str, it: &fn(&'a str) -> bool) -> bool { * Fails during iteration if the string contains a non-whitespace * sequence longer than the limit. */ -pub fn _each_split_within<'a>(ss: &'a str, +pub fn each_split_within<'a>(ss: &'a str, lim: uint, it: &fn(&'a str) -> bool) -> bool { // Just for fun, let's write this as an state machine: @@ -886,12 +908,6 @@ pub fn _each_split_within<'a>(ss: &'a str, return cont; } -pub fn each_split_within<'a>(ss: &'a str, - lim: uint, - it: &fn(&'a str) -> bool) -> bool { - _each_split_within(ss, lim, it) -} - /** * Replace all occurrences of one string with another * @@ -1236,7 +1252,7 @@ pub fn each_char_reverse(s: &str, it: &fn(char) -> bool) -> bool { each_chari_reverse(s, |_, c| it(c)) } -// Iterates over the chars in a string in reverse, with indices +/// Iterates over the chars in a string in reverse, with indices #[inline(always)] pub fn each_chari_reverse(s: &str, it: &fn(uint, char) -> bool) -> bool { let mut pos = s.len(); @@ -1814,6 +1830,12 @@ pub fn to_utf16(s: &str) -> ~[u16] { u } +/// Iterates over the utf-16 characters in the specified slice, yielding each +/// decoded unicode character to the function provided. +/// +/// # Failures +/// +/// * Fails on invalid utf-16 data pub fn utf16_chars(v: &[u16], f: &fn(char)) { let len = v.len(); let mut i = 0u; @@ -1838,6 +1860,9 @@ pub fn utf16_chars(v: &[u16], f: &fn(char)) { } } +/** + * Allocates a new string from the utf-16 slice provided + */ pub fn from_utf16(v: &[u16]) -> ~str { let mut buf = ~""; reserve(&mut buf, v.len()); @@ -1845,6 +1870,10 @@ pub fn from_utf16(v: &[u16]) -> ~str { buf } +/** + * Allocates a new string with the specified capacity. The string returned is + * the empty string, but has capacity for much more. + */ pub fn with_capacity(capacity: uint) -> ~str { let mut buf = ~""; reserve(&mut buf, capacity); @@ -1990,6 +2019,7 @@ pub fn char_at(s: &str, i: uint) -> char { return char_range_at(s, i).ch; } +#[allow(missing_doc)] pub struct CharRange { ch: char, next: uint @@ -2481,6 +2511,7 @@ pub mod traits { #[cfg(test)] pub mod traits {} +#[allow(missing_doc)] pub trait StrSlice<'self> { fn all(&self, it: &fn(char) -> bool) -> bool; fn any(&self, it: &fn(char) -> bool) -> bool; @@ -2715,6 +2746,7 @@ impl<'self> StrSlice<'self> for &'self str { fn to_bytes(&self) -> ~[u8] { to_bytes(*self) } } +#[allow(missing_doc)] pub trait OwnedStr { fn push_str(&mut self, v: &str); fn push_char(&mut self, c: char); @@ -2738,6 +2770,8 @@ impl Clone for ~str { } } +/// External iterator for a string's characters. Use with the `std::iterator` +/// module. pub struct StrCharIterator<'self> { priv index: uint, priv string: &'self str, diff --git a/src/libstd/sys.rs b/src/libstd/sys.rs index 137070ce20211..5d020e229e28d 100644 --- a/src/libstd/sys.rs +++ b/src/libstd/sys.rs @@ -10,6 +10,8 @@ //! Misc low level stuff +#[allow(missing_doc)]; + use option::{Some, None}; use cast; use cmp::{Eq, Ord}; diff --git a/src/libstd/task/local_data_priv.rs b/src/libstd/task/local_data_priv.rs index d3757ea3f4faf..f6b14a5153970 100644 --- a/src/libstd/task/local_data_priv.rs +++ b/src/libstd/task/local_data_priv.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + use cast; use cmp::Eq; use libc; diff --git a/src/libstd/task/mod.rs b/src/libstd/task/mod.rs index 9c9a91f954856..28fb73e6eef52 100644 --- a/src/libstd/task/mod.rs +++ b/src/libstd/task/mod.rs @@ -33,6 +33,8 @@ * ~~~ */ +#[allow(missing_doc)]; + use prelude::*; use cast; diff --git a/src/libstd/to_bytes.rs b/src/libstd/to_bytes.rs index 20b45dfb2cc6a..77e7583ebe532 100644 --- a/src/libstd/to_bytes.rs +++ b/src/libstd/to_bytes.rs @@ -303,7 +303,11 @@ impl IterBytes for *const A { } } +/// A trait for converting a value to a list of bytes. pub trait ToBytes { + /// Converts the current value to a list of bytes. This is equivalent to + /// invoking iter_bytes on a type and collecting all yielded values in an + /// array fn to_bytes(&self, lsb0: bool) -> ~[u8]; } diff --git a/src/libstd/to_str.rs b/src/libstd/to_str.rs index 9ca54066289a3..b4298ef069128 100644 --- a/src/libstd/to_str.rs +++ b/src/libstd/to_str.rs @@ -22,13 +22,15 @@ use hash::Hash; use cmp::Eq; use old_iter::BaseIter; +/// A generic trait for converting a value to a string pub trait ToStr { + /// Converts the value of `self` to an owned string fn to_str(&self) -> ~str; } /// Trait for converting a type to a string, consuming it in the process. pub trait ToStrConsume { - // Cosume and convert to a string. + /// Cosume and convert to a string. fn to_str_consume(self) -> ~str; } diff --git a/src/libstd/trie.rs b/src/libstd/trie.rs index 1490841b7e651..460f29d597ac4 100644 --- a/src/libstd/trie.rs +++ b/src/libstd/trie.rs @@ -28,6 +28,7 @@ enum Child { Nothing } +#[allow(missing_doc)] pub struct TrieMap { priv root: TrieNode, priv length: uint @@ -172,6 +173,7 @@ pub impl TrieMap { } } +#[allow(missing_doc)] pub struct TrieSet { priv map: TrieMap<()> } diff --git a/src/libstd/tuple.rs b/src/libstd/tuple.rs index 639df89a3776f..da2c52014e8f6 100644 --- a/src/libstd/tuple.rs +++ b/src/libstd/tuple.rs @@ -10,14 +10,20 @@ //! Operations on tuples +#[allow(missing_doc)]; + use kinds::Copy; use vec; pub use self::inner::*; +/// Method extensions to pairs where both types satisfy the `Copy` bound pub trait CopyableTuple { + /// Return the first element of self fn first(&self) -> T; + /// Return the second element of self fn second(&self) -> U; + /// Return the results of swapping the two elements of self fn swap(&self) -> (U, T); } @@ -47,8 +53,12 @@ impl CopyableTuple for (T, U) { } } +/// Method extensions for pairs where the types don't necessarily satisfy the +/// `Copy` bound pub trait ImmutableTuple { + /// Return a reference to the first element of self fn first_ref<'a>(&'a self) -> &'a T; + /// Return a reference to the second element of self fn second_ref<'a>(&'a self) -> &'a U; } diff --git a/src/libstd/unicode.rs b/src/libstd/unicode.rs index ce584c0f1ba6f..f8f56c75a295c 100644 --- a/src/libstd/unicode.rs +++ b/src/libstd/unicode.rs @@ -10,6 +10,8 @@ // The following code was generated by "src/etc/unicode.py" +#[allow(missing_doc)]; + pub mod general_category { fn bsearch_range_table(c: char, r: &'static [(char,char)]) -> bool { diff --git a/src/libstd/util.rs b/src/libstd/util.rs index 5539881a6481f..18fc6af3ac66b 100644 --- a/src/libstd/util.rs +++ b/src/libstd/util.rs @@ -107,13 +107,14 @@ pub unsafe fn replace_ptr(dest: *mut T, mut src: T) -> T { /// A non-copyable dummy type. pub struct NonCopyable { - i: (), + priv i: (), } impl Drop for NonCopyable { fn finalize(&self) { } } +/// Creates a dummy non-copyable structure and returns it for use. pub fn NonCopyable() -> NonCopyable { NonCopyable { i: () } } diff --git a/src/libstd/vec.rs b/src/libstd/vec.rs index 33e7b0a97c42a..c02d87923c04b 100644 --- a/src/libstd/vec.rs +++ b/src/libstd/vec.rs @@ -129,6 +129,7 @@ pub fn len(v: &const [T]) -> uint { } // A botch to tide us over until core and std are fully demuted. +#[allow(missing_doc)] pub fn uniq_len(v: &const ~[T]) -> uint { unsafe { let v: &~[T] = transmute(v); @@ -543,6 +544,22 @@ pub fn remove(v: &mut ~[T], i: uint) -> T { v.pop() } +/// Consumes all elements, in a vector, moving them out into the / closure +/// provided. The vector is traversed from the start to the end. +/// +/// This method does not impose any requirements on the type of the vector being +/// consumed, but it prevents any usage of the vector after this function is +/// called. +/// +/// # Examples +/// +/// ~~~ {.rust} +/// let v = ~[~"a", ~"b"]; +/// do vec::consume(v) |i, s| { +/// // s has type ~str, not &~str +/// io::println(s + fmt!(" %d", i)); +/// } +/// ~~~ pub fn consume(mut v: ~[T], f: &fn(uint, v: T)) { unsafe { do as_mut_buf(v) |p, ln| { @@ -561,6 +578,12 @@ pub fn consume(mut v: ~[T], f: &fn(uint, v: T)) { } } +/// Consumes all elements, in a vector, moving them out into the / closure +/// provided. The vectors is traversed in reverse order (from end to start). +/// +/// This method does not impose any requirements on the type of the vector being +/// consumed, but it prevents any usage of the vector after this function is +/// called. pub fn consume_reverse(mut v: ~[T], f: &fn(uint, v: T)) { unsafe { do as_mut_buf(v) |p, ln| { @@ -646,6 +669,16 @@ fn push_slow(v: &mut ~[T], initval: T) { unsafe { push_fast(v, initval) } } +/// Iterates over the slice `rhs`, copies each element, and then appends it to +/// the vector provided `v`. The `rhs` vector is traversed in-order. +/// +/// # Example +/// +/// ~~~ {.rust} +/// let mut a = ~[1]; +/// vec::push_all(&mut a, [2, 3, 4]); +/// assert!(a == ~[1, 2, 3, 4]); +/// ~~~ #[inline(always)] pub fn push_all(v: &mut ~[T], rhs: &const [T]) { let new_len = v.len() + rhs.len(); @@ -656,6 +689,17 @@ pub fn push_all(v: &mut ~[T], rhs: &const [T]) { } } +/// Takes ownership of the vector `rhs`, moving all elements into the specified +/// vector `v`. This does not copy any elements, and it is illegal to use the +/// `rhs` vector after calling this method (because it is moved here). +/// +/// # Example +/// +/// ~~~ {.rust} +/// let mut a = ~[~1]; +/// vec::push_all_move(&mut a, ~[~2, ~3, ~4]); +/// assert!(a == ~[~1, ~2, ~3, ~4]); +/// ~~~ #[inline(always)] pub fn push_all_move(v: &mut ~[T], mut rhs: ~[T]) { let new_len = v.len() + rhs.len(); @@ -724,6 +768,9 @@ pub fn dedup(v: &mut ~[T]) { } // Appending + +/// Iterates over the `rhs` vector, copying each element and appending it to the +/// `lhs`. Afterwards, the `lhs` is then returned for use again. #[inline(always)] pub fn append(lhs: ~[T], rhs: &const [T]) -> ~[T] { let mut v = lhs; @@ -731,6 +778,8 @@ pub fn append(lhs: ~[T], rhs: &const [T]) -> ~[T] { v } +/// Appends one element to the vector provided. The vector itself is then +/// returned for use again. #[inline(always)] pub fn append_one(lhs: ~[T], x: T) -> ~[T] { let mut v = lhs; @@ -806,6 +855,13 @@ pub fn map(v: &[T], f: &fn(t: &T) -> U) -> ~[U] { result } +/// Consumes a vector, mapping it into a different vector. This function takes +/// ownership of the supplied vector `v`, moving each element into the closure +/// provided to generate a new element. The vector of new elements is then +/// returned. +/// +/// The original vector `v` cannot be used after this function call (it is moved +/// inside), but there are no restrictions on the type of the vector. pub fn map_consume(v: ~[T], f: &fn(v: T) -> U) -> ~[U] { let mut result = ~[]; do consume(v) |_i, x| { @@ -1444,8 +1500,8 @@ pub fn reversed(v: &const [T]) -> ~[T] { * ~~~ */ #[inline(always)] -pub fn _each<'r,T>(v: &'r [T], f: &fn(&'r T) -> bool) -> bool { - // ^^^^ +pub fn each<'r,T>(v: &'r [T], f: &fn(&'r T) -> bool) -> bool { + // ^^^^ // NB---this CANNOT be &const [T]! The reason // is that you are passing it to `f()` using // an immutable. @@ -1467,13 +1523,11 @@ pub fn _each<'r,T>(v: &'r [T], f: &fn(&'r T) -> bool) -> bool { return true; } -pub fn each<'r,T>(v: &'r [T], f: &fn(&'r T) -> bool) -> bool { _each(v, f) } - /// Like `each()`, but for the case where you have /// a vector with mutable contents and you would like /// to mutate the contents as you iterate. #[inline(always)] -pub fn _each_mut<'r,T>(v: &'r mut [T], f: &fn(elem: &'r mut T) -> bool) -> bool { +pub fn each_mut<'r,T>(v: &'r mut [T], f: &fn(elem: &'r mut T) -> bool) -> bool { let mut broke = false; do as_mut_buf(v) |p, n| { let mut n = n; @@ -1491,14 +1545,10 @@ pub fn _each_mut<'r,T>(v: &'r mut [T], f: &fn(elem: &'r mut T) -> bool) -> bool return broke; } -pub fn each_mut<'r,T>(v: &'r mut [T], f: &fn(elem: &'r mut T) -> bool) -> bool { - _each_mut(v, f) -} - /// Like `each()`, but for the case where you have a vector that *may or may /// not* have mutable contents. #[inline(always)] -pub fn _each_const(v: &const [T], f: &fn(elem: &const T) -> bool) -> bool { +pub fn each_const(v: &const [T], f: &fn(elem: &const T) -> bool) -> bool { let mut i = 0; let n = v.len(); while i < n { @@ -1510,17 +1560,13 @@ pub fn _each_const(v: &const [T], f: &fn(elem: &const T) -> bool) -> bool { return true; } -pub fn each_const(v: &const [t], f: &fn(elem: &const t) -> bool) -> bool { - _each_const(v, f) -} - /** * Iterates over a vector's elements and indices * * Return true to continue, false to break. */ #[inline(always)] -pub fn _eachi<'r,T>(v: &'r [T], f: &fn(uint, v: &'r T) -> bool) -> bool { +pub fn eachi<'r,T>(v: &'r [T], f: &fn(uint, v: &'r T) -> bool) -> bool { let mut i = 0; for each(v) |p| { if !f(i, p) { return false; } @@ -1529,18 +1575,14 @@ pub fn _eachi<'r,T>(v: &'r [T], f: &fn(uint, v: &'r T) -> bool) -> bool { return true; } -pub fn eachi<'r,T>(v: &'r [T], f: &fn(uint, v: &'r T) -> bool) -> bool { - _eachi(v, f) -} - /** * Iterates over a mutable vector's elements and indices * * Return true to continue, false to break. */ #[inline(always)] -pub fn _eachi_mut<'r,T>(v: &'r mut [T], - f: &fn(uint, v: &'r mut T) -> bool) -> bool { +pub fn eachi_mut<'r,T>(v: &'r mut [T], + f: &fn(uint, v: &'r mut T) -> bool) -> bool { let mut i = 0; for each_mut(v) |p| { if !f(i, p) { @@ -1551,23 +1593,14 @@ pub fn _eachi_mut<'r,T>(v: &'r mut [T], return true; } -pub fn eachi_mut<'r,T>(v: &'r mut [T], - f: &fn(uint, v: &'r mut T) -> bool) -> bool { - _eachi_mut(v, f) -} - /** * Iterates over a vector's elements in reverse * * Return true to continue, false to break. */ #[inline(always)] -pub fn _each_reverse<'r,T>(v: &'r [T], blk: &fn(v: &'r T) -> bool) -> bool { - _eachi_reverse(v, |_i, v| blk(v)) -} - pub fn each_reverse<'r,T>(v: &'r [T], blk: &fn(v: &'r T) -> bool) -> bool { - _each_reverse(v, blk) + eachi_reverse(v, |_i, v| blk(v)) } /** @@ -1576,7 +1609,7 @@ pub fn each_reverse<'r,T>(v: &'r [T], blk: &fn(v: &'r T) -> bool) -> bool { * Return true to continue, false to break. */ #[inline(always)] -pub fn _eachi_reverse<'r,T>(v: &'r [T], +pub fn eachi_reverse<'r,T>(v: &'r [T], blk: &fn(i: uint, v: &'r T) -> bool) -> bool { let mut i = v.len(); while i > 0 { @@ -1588,11 +1621,6 @@ pub fn _eachi_reverse<'r,T>(v: &'r [T], return true; } -pub fn eachi_reverse<'r,T>(v: &'r [T], - blk: &fn(i: uint, v: &'r T) -> bool) -> bool { - _eachi_reverse(v, blk) -} - /** * Iterates over two vectors simultaneously * @@ -1601,7 +1629,7 @@ pub fn eachi_reverse<'r,T>(v: &'r [T], * Both vectors must have the same length */ #[inline] -pub fn _each2(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool { +pub fn each2(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool { assert_eq!(v1.len(), v2.len()); for uint::range(0u, v1.len()) |i| { if !f(&v1[i], &v2[i]) { @@ -1611,10 +1639,6 @@ pub fn _each2(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool { return true; } -pub fn each2(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool { - _each2(v1, v2, f) -} - /** * * Iterates over two vector with mutable. @@ -1624,7 +1648,8 @@ pub fn each2(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool { * Both vectors must have the same length */ #[inline] -pub fn _each2_mut(v1: &mut [U], v2: &mut [T], f: &fn(u: &mut U, t: &mut T) -> bool) -> bool { +pub fn each2_mut(v1: &mut [U], v2: &mut [T], + f: &fn(u: &mut U, t: &mut T) -> bool) -> bool { assert_eq!(v1.len(), v2.len()); for uint::range(0u, v1.len()) |i| { if !f(&mut v1[i], &mut v2[i]) { @@ -1634,10 +1659,6 @@ pub fn _each2_mut(v1: &mut [U], v2: &mut [T], f: &fn(u: &mut U, t: &mut T) return true; } -pub fn each2_mut(v1: &mut [U], v2: &mut [T], f: &fn(u: &mut U, t: &mut T) -> bool) -> bool { - _each2_mut(v1, v2, f) -} - /** * Iterate over all permutations of vector `v`. * @@ -1761,6 +1782,9 @@ pub fn as_mut_buf(s: &mut [T], f: &fn(*mut T, uint) -> U) -> U { // Equality +/// Tests whether two slices are equal to one another. This is only true if both +/// slices are of the same length, and each of the corresponding elements return +/// true when queried via the `eq` function. fn eq(a: &[T], b: &[T]) -> bool { let (a_len, b_len) = (a.len(), b.len()); if a_len != b_len { return false; } @@ -1773,6 +1797,9 @@ fn eq(a: &[T], b: &[T]) -> bool { true } +/// Similar to the `vec::eq` function, but this is defined for types which +/// implement `TotalEq` as opposed to types which implement `Eq`. Equality +/// comparisons are done via the `equals` function instead of `eq`. fn equals(a: &[T], b: &[T]) -> bool { let (a_len, b_len) = (a.len(), b.len()); if a_len != b_len { return false; } @@ -1946,6 +1973,7 @@ impl<'self,T> Container for &'self const [T] { fn len(&const self) -> uint { len(*self) } } +#[allow(missing_doc)] pub trait CopyableVector { fn to_owned(&self) -> ~[T]; } @@ -1965,6 +1993,7 @@ impl<'self,T:Copy> CopyableVector for &'self [T] { } } +#[allow(missing_doc)] pub trait ImmutableVector<'self, T> { fn slice(&self, start: uint, end: uint) -> &'self [T]; fn iter(self) -> VecIterator<'self, T>; @@ -2140,6 +2169,7 @@ impl<'self,T> ImmutableVector<'self, T> for &'self [T] { } } +#[allow(missing_doc)] pub trait ImmutableEqVector { fn position_elem(&self, t: &T) -> Option; fn rposition_elem(&self, t: &T) -> Option; @@ -2159,6 +2189,7 @@ impl<'self,T:Eq> ImmutableEqVector for &'self [T] { } } +#[allow(missing_doc)] pub trait ImmutableCopyableVector { fn filtered(&self, f: &fn(&T) -> bool) -> ~[T]; fn rfind(&self, f: &fn(t: &T) -> bool) -> Option; @@ -2208,6 +2239,7 @@ impl<'self,T:Copy> ImmutableCopyableVector for &'self [T] { } } +#[allow(missing_doc)] pub trait OwnedVector { fn push(&mut self, t: T); fn push_all_move(&mut self, rhs: ~[T]); @@ -2312,6 +2344,7 @@ impl Mutable for ~[T] { fn clear(&mut self) { self.truncate(0) } } +#[allow(missing_doc)] pub trait OwnedCopyableVector { fn push_all(&mut self, rhs: &const [T]); fn grow(&mut self, n: uint, initval: &T); @@ -2335,6 +2368,7 @@ impl OwnedCopyableVector for ~[T] { } } +#[allow(missing_doc)] trait OwnedEqVector { fn dedup(&mut self); } @@ -2346,6 +2380,7 @@ impl OwnedEqVector for ~[T] { } } +#[allow(missing_doc)] pub trait MutableVector<'self, T> { fn mut_slice(self, start: uint, end: uint) -> &'self mut [T]; @@ -2386,6 +2421,7 @@ pub unsafe fn from_buf(ptr: *T, elts: uint) -> ~[T] { } /// The internal 'unboxed' representation of a vector +#[allow(missing_doc)] pub struct UnboxedVecRepr { fill: uint, alloc: uint, @@ -2405,13 +2441,17 @@ pub mod raw { use util; /// The internal representation of a (boxed) vector + #[allow(missing_doc)] pub struct VecRepr { box_header: managed::raw::BoxHeaderRepr, unboxed: UnboxedVecRepr } + /// The internal representation of a slice pub struct SliceRepr { + /// Pointer to the base of this slice data: *u8, + /// The length of the slice len: uint } @@ -2855,13 +2895,14 @@ impl Clone for ~[A] { } } -// could be implemented with &[T] with .slice(), but this avoids bounds checks +/// An external iterator for vectors (use with the std::iterator module) pub struct VecIterator<'self, T> { priv ptr: *T, priv end: *T, priv lifetime: &'self T // FIXME: #5922 } +// could be implemented with &[T] with .slice(), but this avoids bounds checks impl<'self, T> Iterator<&'self T> for VecIterator<'self, T> { #[inline] fn next(&mut self) -> Option<&'self T> { From 395685079a2ef21c93a90ff6ccac2873b3013c7f Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 28 May 2013 22:11:41 -0500 Subject: [PATCH 4/4] libextra: Require documentation by default --- src/libextra/arc.rs | 2 ++ src/libextra/arena.rs | 2 ++ src/libextra/base64.rs | 4 ++++ src/libextra/bitv.rs | 4 +++- src/libextra/dbg.rs | 2 ++ src/libextra/deque.rs | 1 + src/libextra/dlist.rs | 3 +++ src/libextra/ebml.rs | 2 ++ src/libextra/fileinput.rs | 2 ++ src/libextra/flate.rs | 2 ++ src/libextra/flatpipes.rs | 2 ++ src/libextra/future.rs | 2 ++ src/libextra/getopts.rs | 2 ++ src/libextra/io_util.rs | 8 ++++++-- src/libextra/json.rs | 20 +++++++++++++++++++- src/libextra/md4.rs | 6 ++++++ src/libextra/net_ip.rs | 2 ++ src/libextra/net_tcp.rs | 2 ++ src/libextra/net_url.rs | 2 ++ src/libextra/num/bigint.rs | 2 ++ src/libextra/num/complex.rs | 2 ++ src/libextra/num/rational.rs | 4 ++-- src/libextra/priority_queue.rs | 1 + src/libextra/rc.rs | 2 ++ src/libextra/rope.rs | 2 ++ src/libextra/semver.rs | 2 ++ src/libextra/serialize.rs | 1 + src/libextra/smallintmap.rs | 4 ++++ src/libextra/sort.rs | 2 ++ src/libextra/stats.rs | 2 ++ src/libextra/std.rc | 6 +++++- src/libextra/task_pool.rs | 2 ++ src/libextra/tempfile.rs | 2 ++ src/libextra/term.rs | 2 ++ src/libextra/time.rs | 2 ++ src/libextra/treemap.rs | 4 ++++ src/libextra/unicode.rs | 1 + src/libextra/uv_iotask.rs | 2 ++ src/libextra/uv_ll.rs | 1 + src/libextra/workcache.rs | 2 ++ src/libstd/run.rs | 2 ++ 41 files changed, 113 insertions(+), 7 deletions(-) diff --git a/src/libextra/arc.rs b/src/libextra/arc.rs index e73b49044d421..1de2003aa99d5 100644 --- a/src/libextra/arc.rs +++ b/src/libextra/arc.rs @@ -37,6 +37,8 @@ * ~~~ */ +#[allow(missing_doc)]; + use core::prelude::*; use sync; diff --git a/src/libextra/arena.rs b/src/libextra/arena.rs index 690993e7bf9a2..7cd63cd03b1aa 100644 --- a/src/libextra/arena.rs +++ b/src/libextra/arena.rs @@ -32,6 +32,8 @@ // overhead when initializing plain-old-data and means we don't need // to waste time running the destructors of POD. +#[allow(missing_doc)]; + use core::prelude::*; use list::{MutList, MutCons, MutNil}; diff --git a/src/libextra/base64.rs b/src/libextra/base64.rs index 373bebeec71ce..b8f3a267d2d24 100644 --- a/src/libextra/base64.rs +++ b/src/libextra/base64.rs @@ -15,7 +15,10 @@ use core::prelude::*; use core::str; use core::vec; +/// A trait for converting a value to base64 encoding. pub trait ToBase64 { + /// Converts the value of `self` to a base64 value, returning the owned + /// string fn to_base64(&self) -> ~str; } @@ -112,6 +115,7 @@ impl<'self> ToBase64 for &'self str { } } +#[allow(missing_doc)] pub trait FromBase64 { fn from_base64(&self) -> ~[u8]; } diff --git a/src/libextra/bitv.rs b/src/libextra/bitv.rs index afd82d425891b..672a61b1ad8dd 100644 --- a/src/libextra/bitv.rs +++ b/src/libextra/bitv.rs @@ -211,9 +211,11 @@ enum BitvVariant { Big(~BigBitv), Small(~SmallBitv) } enum Op {Union, Intersect, Assign, Difference} -// The bitvector type +/// The bitvector type pub struct Bitv { + /// Internal representation of the bit vector (small or large) rep: BitvVariant, + /// The number of valid bits in the internal representation nbits: uint } diff --git a/src/libextra/dbg.rs b/src/libextra/dbg.rs index 4b2d2a60a68ef..cbd7cb5e3c08f 100644 --- a/src/libextra/dbg.rs +++ b/src/libextra/dbg.rs @@ -10,6 +10,8 @@ //! Unsafe debugging functions for inspecting values. +#[allow(missing_doc)]; + use core::cast::transmute; use core::sys; diff --git a/src/libextra/deque.rs b/src/libextra/deque.rs index ccb52fa038c12..08dc2436c9339 100644 --- a/src/libextra/deque.rs +++ b/src/libextra/deque.rs @@ -18,6 +18,7 @@ use core::vec; static initial_capacity: uint = 32u; // 2^5 +#[allow(missing_doc)] pub struct Deque { priv nelts: uint, priv lo: uint, diff --git a/src/libextra/dlist.rs b/src/libextra/dlist.rs index fc6cdb102a0ef..5581c6d5ac9d9 100644 --- a/src/libextra/dlist.rs +++ b/src/libextra/dlist.rs @@ -26,6 +26,7 @@ use core::vec; pub type DListLink = Option<@mut DListNode>; +#[allow(missing_doc)] pub struct DListNode { data: T, linked: bool, // for assertions @@ -33,6 +34,7 @@ pub struct DListNode { next: DListLink, } +#[allow(missing_doc)] pub struct DList { size: uint, hd: DListLink, @@ -106,6 +108,7 @@ pub fn from_elem(data: T) -> @mut DList { list } +/// Creates a new dlist from a vector of elements, maintaining the same order pub fn from_vec(vec: &[T]) -> @mut DList { do vec::foldl(DList(), vec) |list,data| { list.push(*data); // Iterating left-to-right -- add newly to the tail. diff --git a/src/libextra/ebml.rs b/src/libextra/ebml.rs index 762328a2e0f64..70beaa58d07b7 100644 --- a/src/libextra/ebml.rs +++ b/src/libextra/ebml.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + use core::prelude::*; // Simple Extensible Binary Markup Language (ebml) reader and writer on a diff --git a/src/libextra/fileinput.rs b/src/libextra/fileinput.rs index e6f3fba6b157f..5cc0875cb51b5 100644 --- a/src/libextra/fileinput.rs +++ b/src/libextra/fileinput.rs @@ -94,6 +94,8 @@ total line count). } */ +#[allow(missing_doc)]; + use core::prelude::*; use core::io::ReaderUtil; diff --git a/src/libextra/flate.rs b/src/libextra/flate.rs index e24c80b4463c3..076126e04329c 100644 --- a/src/libextra/flate.rs +++ b/src/libextra/flate.rs @@ -14,6 +14,8 @@ Simple compression */ +#[allow(missing_doc)]; + use core::prelude::*; use core::libc::{c_void, size_t, c_int}; diff --git a/src/libextra/flatpipes.rs b/src/libextra/flatpipes.rs index 955da13c7b38b..2f5a43d8e84dd 100644 --- a/src/libextra/flatpipes.rs +++ b/src/libextra/flatpipes.rs @@ -47,6 +47,8 @@ block the scheduler thread, so will their pipes. */ +#[allow(missing_doc)]; + use core::prelude::*; // The basic send/recv interface FlatChan and PortChan will implement diff --git a/src/libextra/future.rs b/src/libextra/future.rs index 38df0c6a2085c..4d3a757e80ed4 100644 --- a/src/libextra/future.rs +++ b/src/libextra/future.rs @@ -23,6 +23,8 @@ * ~~~ */ +#[allow(missing_doc)]; + use core::prelude::*; use core::cast; diff --git a/src/libextra/getopts.rs b/src/libextra/getopts.rs index 3c223fe05d410..294b8fec04236 100644 --- a/src/libextra/getopts.rs +++ b/src/libextra/getopts.rs @@ -78,6 +78,8 @@ * ``` */ +#[allow(missing_doc)]; + use core::prelude::*; use core::cmp::Eq; diff --git a/src/libextra/io_util.rs b/src/libextra/io_util.rs index 7d43663cc808b..91424ae3ba2c0 100644 --- a/src/libextra/io_util.rs +++ b/src/libextra/io_util.rs @@ -11,12 +11,16 @@ use core::io::{Reader, BytesReader}; use core::io; +/// An implementation of the io::Reader interface which reads a buffer of bytes pub struct BufReader { + /// The buffer of bytes to read buf: ~[u8], + /// The current position in the buffer of bytes pos: @mut uint } -pub impl BufReader { +impl BufReader { + /// Creates a new buffer reader for the specified buffer pub fn new(v: ~[u8]) -> BufReader { BufReader { buf: v, @@ -24,7 +28,7 @@ pub impl BufReader { } } - priv fn as_bytes_reader(&self, f: &fn(&BytesReader) -> A) -> A { + fn as_bytes_reader(&self, f: &fn(&BytesReader) -> A) -> A { // Recreating the BytesReader state every call since // I can't get the borrowing to work correctly let bytes_reader = BytesReader { diff --git a/src/libextra/json.rs b/src/libextra/json.rs index c3ef346dba3ba..48a3288f80903 100644 --- a/src/libextra/json.rs +++ b/src/libextra/json.rs @@ -43,9 +43,14 @@ pub type List = ~[Json]; pub type Object = HashMap<~str, Json>; #[deriving(Eq)] +/// If an error occurs while parsing some JSON, this is the structure which is +/// returned pub struct Error { + /// The line number at which the error occurred line: uint, + /// The column number at which the error occurred col: uint, + /// A message describing the type of the error msg: @~str, } @@ -75,10 +80,13 @@ fn spaces(n: uint) -> ~str { return ss; } +/// A structure for implementing serialization to JSON. pub struct Encoder { priv wr: @io::Writer, } +/// Creates a new JSON encoder whose output will be written to the writer +/// specified. pub fn Encoder(wr: @io::Writer) -> Encoder { Encoder { wr: wr @@ -228,11 +236,14 @@ impl serialize::Encoder for Encoder { } } +/// Another encoder for JSON, but prints out human-readable JSON instead of +/// compact data pub struct PrettyEncoder { priv wr: @io::Writer, priv indent: uint, } +/// Creates a new encoder whose output will be written to the specified writer pub fn PrettyEncoder(wr: @io::Writer) -> PrettyEncoder { PrettyEncoder { wr: wr, @@ -468,6 +479,7 @@ pub fn to_pretty_str(json: &Json) -> ~str { io::with_str_writer(|wr| to_pretty_writer(wr, json)) } +#[allow(missing_doc)] pub struct Parser { priv rdr: @io::Reader, priv ch: char, @@ -846,10 +858,12 @@ pub fn from_str(s: &str) -> Result { } } +/// A structure to decode JSON to values in rust. pub struct Decoder { priv stack: ~[Json], } +/// Creates a new decoder instance for decoding the specified JSON value. pub fn Decoder(json: Json) -> Decoder { Decoder { stack: ~[json] @@ -1200,7 +1214,11 @@ impl Ord for Json { fn gt(&self, other: &Json) -> bool { (*other).lt(&(*self)) } } -trait ToJson { fn to_json(&self) -> Json; } +/// A trait for converting values to JSON +trait ToJson { + /// Converts the value of `self` to an instance of JSON + fn to_json(&self) -> Json; +} impl ToJson for Json { fn to_json(&self) -> Json { copy *self } diff --git a/src/libextra/md4.rs b/src/libextra/md4.rs index 9873d7fcd8e35..0f05e50ea7024 100644 --- a/src/libextra/md4.rs +++ b/src/libextra/md4.rs @@ -21,6 +21,8 @@ struct Quad { d: u32 } +/// Calculates the md4 hash of the given slice of bytes, returning the 128-bit +/// result as a quad of u32's pub fn md4(msg: &[u8]) -> Quad { // subtle: if orig_len is merely uint, then the code below // which performs shifts by 32 bits or more has undefined @@ -105,6 +107,8 @@ pub fn md4(msg: &[u8]) -> Quad { return Quad {a: a, b: b, c: c, d: d}; } +/// Calculates the md4 hash of a slice of bytes, returning the hex-encoded +/// version of the hash pub fn md4_str(msg: &[u8]) -> ~str { let Quad {a, b, c, d} = md4(msg); fn app(a: u32, b: u32, c: u32, d: u32, f: &fn(u32)) { @@ -123,6 +127,8 @@ pub fn md4_str(msg: &[u8]) -> ~str { result } +/// Calculates the md4 hash of a string, returning the hex-encoded version of +/// the hash pub fn md4_text(msg: &str) -> ~str { md4_str(str::to_bytes(msg)) } #[test] diff --git a/src/libextra/net_ip.rs b/src/libextra/net_ip.rs index a9c8540a83cc9..e92523726dfaa 100644 --- a/src/libextra/net_ip.rs +++ b/src/libextra/net_ip.rs @@ -10,6 +10,8 @@ //! Types/fns concerning Internet Protocol (IP), versions 4 & 6 +#[allow(missing_doc)]; + use core::prelude::*; use core::libc; diff --git a/src/libextra/net_tcp.rs b/src/libextra/net_tcp.rs index 8dff9b330a5b0..c3a0463c2fc87 100644 --- a/src/libextra/net_tcp.rs +++ b/src/libextra/net_tcp.rs @@ -11,6 +11,8 @@ //! High-level interface to libuv's TCP functionality // FIXME #4425: Need FFI fixes +#[allow(missing_doc)]; + use core::prelude::*; use future; diff --git a/src/libextra/net_url.rs b/src/libextra/net_url.rs index 3b7c808c596ea..fa7295923a008 100644 --- a/src/libextra/net_url.rs +++ b/src/libextra/net_url.rs @@ -10,6 +10,8 @@ //! Types/fns concerning URLs (see RFC 3986) +#[allow(missing_doc)]; + use core::prelude::*; use core::cmp::Eq; diff --git a/src/libextra/num/bigint.rs b/src/libextra/num/bigint.rs index 263618ed56f9b..adbaf89e16c47 100644 --- a/src/libextra/num/bigint.rs +++ b/src/libextra/num/bigint.rs @@ -597,6 +597,8 @@ impl BigUint { } + /// Converts this big integer into a uint, returning the uint::max_value if + /// it's too large to fit in a uint. pub fn to_uint(&self) -> uint { match self.data.len() { 0 => 0, diff --git a/src/libextra/num/complex.rs b/src/libextra/num/complex.rs index 09bd66232eb04..10bfe9409daa4 100644 --- a/src/libextra/num/complex.rs +++ b/src/libextra/num/complex.rs @@ -25,7 +25,9 @@ use core::num::{Zero,One,ToStrRadix}; /// A complex number in Cartesian form. #[deriving(Eq,Clone)] pub struct Cmplx { + /// Real portion of the complex number re: T, + /// Imaginary portion of the complex number im: T } diff --git a/src/libextra/num/rational.rs b/src/libextra/num/rational.rs index b33d113161c36..1a8ab75b3dd0d 100644 --- a/src/libextra/num/rational.rs +++ b/src/libextra/num/rational.rs @@ -8,7 +8,6 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. - //! Rational numbers use core::prelude::*; @@ -22,6 +21,7 @@ use super::bigint::BigInt; /// Represents the ratio between 2 numbers. #[deriving(Clone)] +#[allow(missing_doc)] pub struct Ratio { numer: T, denom: T @@ -49,7 +49,7 @@ impl Ratio { numer: numer, denom: denom } } - // Create a new Ratio. Fails if `denom == 0`. + /// Create a new Ratio. Fails if `denom == 0`. #[inline(always)] pub fn new(numer: T, denom: T) -> Ratio { if denom == Zero::zero() { diff --git a/src/libextra/priority_queue.rs b/src/libextra/priority_queue.rs index 9345c24675091..49fbf06406f4e 100644 --- a/src/libextra/priority_queue.rs +++ b/src/libextra/priority_queue.rs @@ -17,6 +17,7 @@ use core::unstable::intrinsics::{move_val_init, init}; use core::util::{replace, swap}; use core::vec; +#[allow(missing_doc)] pub struct PriorityQueue { priv data: ~[T], } diff --git a/src/libextra/rc.rs b/src/libextra/rc.rs index 73f98a3b19c59..381b8ac05ba36 100644 --- a/src/libextra/rc.rs +++ b/src/libextra/rc.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + /** Task-local reference counted smart pointers Task-local reference counted smart pointers are an alternative to managed boxes with deterministic diff --git a/src/libextra/rope.rs b/src/libextra/rope.rs index 566bbfd6df6a3..413a498a20ec5 100644 --- a/src/libextra/rope.rs +++ b/src/libextra/rope.rs @@ -33,6 +33,8 @@ * * access to a character by index is logarithmic (linear in strings); */ +#[allow(missing_doc)]; + use core::prelude::*; use core::str; diff --git a/src/libextra/semver.rs b/src/libextra/semver.rs index 0b07886772687..494f0c8ea815f 100644 --- a/src/libextra/semver.rs +++ b/src/libextra/semver.rs @@ -10,6 +10,8 @@ //! Semver parsing and logic +#[allow(missing_doc)]; + use core::prelude::*; use core::char; diff --git a/src/libextra/serialize.rs b/src/libextra/serialize.rs index d20aed69240d2..4d2b8d0b50a28 100644 --- a/src/libextra/serialize.rs +++ b/src/libextra/serialize.rs @@ -14,6 +14,7 @@ Core encoding and decoding interfaces. */ +#[allow(missing_doc)]; #[forbid(non_camel_case_types)]; use core::prelude::*; diff --git a/src/libextra/smallintmap.rs b/src/libextra/smallintmap.rs index a85f113b68fb4..98392fc41e1bc 100644 --- a/src/libextra/smallintmap.rs +++ b/src/libextra/smallintmap.rs @@ -23,6 +23,7 @@ use core::uint; use core::util::replace; use core::vec; +#[allow(missing_doc)] pub struct SmallIntMap { priv v: ~[Option], } @@ -186,6 +187,9 @@ pub impl SmallIntMap { } } +/// A set implemented on top of the SmallIntMap type. This set is always a set +/// of integers, and the space requirements are on the order of the highest +/// valued integer in the set. pub struct SmallIntSet { priv map: SmallIntMap<()> } diff --git a/src/libextra/sort.rs b/src/libextra/sort.rs index b3118dd37e12e..420c63efab5d3 100644 --- a/src/libextra/sort.rs +++ b/src/libextra/sort.rs @@ -167,6 +167,7 @@ pub fn quick_sort3(arr: &mut [T]) { qsort3(arr, 0, (len - 1) as int); } +#[allow(missing_doc)] pub trait Sort { fn qsort(self); } @@ -179,6 +180,7 @@ static MIN_MERGE: uint = 64; static MIN_GALLOP: uint = 7; static INITIAL_TMP_STORAGE: uint = 128; +#[allow(missing_doc)] pub fn tim_sort(array: &mut [T]) { let size = array.len(); if size < 2 { diff --git a/src/libextra/stats.rs b/src/libextra/stats.rs index 504930a884ee1..d224777ded702 100644 --- a/src/libextra/stats.rs +++ b/src/libextra/stats.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + use core::prelude::*; use core::vec; diff --git a/src/libextra/std.rc b/src/libextra/std.rc index 8c03701f51310..a81ab3005f6d1 100644 --- a/src/libextra/std.rc +++ b/src/libextra/std.rc @@ -27,8 +27,12 @@ not required in or otherwise suitable for the core library. #[crate_type = "lib"]; #[deny(non_camel_case_types)]; +#[deny(missing_doc)]; + +// NOTE: remove these two attributes after the next snapshot +#[no_core]; // for stage0 +#[allow(unrecognized_lint)]; // otherwise stage0 is seriously ugly -#[no_core]; #[no_std]; extern mod core(name = "std", vers = "0.7-pre"); diff --git a/src/libextra/task_pool.rs b/src/libextra/task_pool.rs index eba4f0d1b75c0..06bc3167040d2 100644 --- a/src/libextra/task_pool.rs +++ b/src/libextra/task_pool.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + /// A task pool abstraction. Useful for achieving predictable CPU /// parallelism. diff --git a/src/libextra/tempfile.rs b/src/libextra/tempfile.rs index c514631e787fb..6d0bd88819500 100644 --- a/src/libextra/tempfile.rs +++ b/src/libextra/tempfile.rs @@ -16,6 +16,8 @@ use core::os; use core::rand::RngUtil; use core::rand; +/// Attempts to make a temporary directory inside of `tmpdir` whose name will +/// have the suffix `suffix`. If no directory can be created, None is returned. pub fn mkdtemp(tmpdir: &Path, suffix: &str) -> Option { let mut r = rand::rng(); for 1000.times { diff --git a/src/libextra/term.rs b/src/libextra/term.rs index 7dace57a1b52b..a76852dc6615a 100644 --- a/src/libextra/term.rs +++ b/src/libextra/term.rs @@ -10,6 +10,8 @@ //! Simple ANSI color library +#[allow(missing_doc)]; + use core::prelude::*; use core::io; diff --git a/src/libextra/time.rs b/src/libextra/time.rs index 93fbf6a405431..8603d0f814a71 100644 --- a/src/libextra/time.rs +++ b/src/libextra/time.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + use core::prelude::*; use core::i32; diff --git a/src/libextra/treemap.rs b/src/libextra/treemap.rs index a05c532c92f6e..e6db84e855cf5 100644 --- a/src/libextra/treemap.rs +++ b/src/libextra/treemap.rs @@ -34,6 +34,7 @@ use core::util::{swap, replace}; // * union: | // These would be convenient since the methods work like `each` +#[allow(missing_doc)] pub struct TreeMap { priv root: Option<~TreeNode>, priv length: uint @@ -242,6 +243,9 @@ impl<'self, T> Iterator<&'self T> for TreeSetIterator<'self, T> { } } +/// A implementation of the `Set` trait on top of the `TreeMap` container. The +/// only requirement is that the type of the elements contained ascribes to the +/// `TotalOrd` trait. pub struct TreeSet { priv map: TreeMap } diff --git a/src/libextra/unicode.rs b/src/libextra/unicode.rs index 77996de6d8394..3bd05a4153447 100644 --- a/src/libextra/unicode.rs +++ b/src/libextra/unicode.rs @@ -9,6 +9,7 @@ // except according to those terms. #[forbid(deprecated_mode)]; +#[allow(missing_doc)]; pub mod icu { pub type UBool = u8; diff --git a/src/libextra/uv_iotask.rs b/src/libextra/uv_iotask.rs index 6cf753b801620..817dfa28aeedf 100644 --- a/src/libextra/uv_iotask.rs +++ b/src/libextra/uv_iotask.rs @@ -15,6 +15,8 @@ * `interact` function you can execute code in a uv callback. */ +#[allow(missing_doc)]; + use core::prelude::*; use ll = uv_ll; diff --git a/src/libextra/uv_ll.rs b/src/libextra/uv_ll.rs index d5f7cb12e4f0b..2cb2eea88283b 100644 --- a/src/libextra/uv_ll.rs +++ b/src/libextra/uv_ll.rs @@ -31,6 +31,7 @@ */ #[allow(non_camel_case_types)]; // C types +#[allow(missing_doc)]; use core::prelude::*; diff --git a/src/libextra/workcache.rs b/src/libextra/workcache.rs index 798cf1ba55d6f..19913fb92f47f 100644 --- a/src/libextra/workcache.rs +++ b/src/libextra/workcache.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[allow(missing_doc)]; + use core::prelude::*; use json; diff --git a/src/libstd/run.rs b/src/libstd/run.rs index 7c73aca3af932..de1148e431b84 100644 --- a/src/libstd/run.rs +++ b/src/libstd/run.rs @@ -10,6 +10,8 @@ //! Process spawning. +#[allow(missing_doc)]; + use cast; use comm::{stream, SharedChan, GenericChan, GenericPort}; use int;