From f276bd7f6619ea480bce772f1696d18bd856c8e2 Mon Sep 17 00:00:00 2001 From: Liigo Zhuang Date: Mon, 22 Sep 2014 17:51:16 +0800 Subject: [PATCH 1/4] cleanup and in summery line docs --- src/liballoc/lib.rs | 2 +- src/libcore/cmp.rs | 10 ++++++---- src/libcore/lib.rs | 2 +- src/librand/isaac.rs | 8 ++++---- src/librand/lib.rs | 5 ++--- src/libstd/lib.rs | 2 +- src/libsyntax/ext/deriving/encodable.rs | 2 ++ src/libunicode/lib.rs | 2 +- 8 files changed, 18 insertions(+), 15 deletions(-) diff --git a/src/liballoc/lib.rs b/src/liballoc/lib.rs index 503c484e469d7..641f7d90463a3 100644 --- a/src/liballoc/lib.rs +++ b/src/liballoc/lib.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! # The Rust core allocation library +//! The Rust core allocation library //! //! This is the lowest level library through which allocation in Rust can be //! performed where the allocation is assumed to succeed. This library will diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs index b90c6daf9ebae..d6ff92c250bd4 100644 --- a/src/libcore/cmp.rs +++ b/src/libcore/cmp.rs @@ -65,8 +65,7 @@ pub trait PartialEq { fn ne(&self, other: &Self) -> bool { !self.eq(other) } } -/// Trait for equality comparisons which are [equivalence relations]( -/// https://en.wikipedia.org/wiki/Equivalence_relation). +/// Trait for equality comparisons which are [equivalence relation] /// /// This means, that in addition to `a == b` and `a != b` being strict /// inverses, the equality must be (for all `a`, `b` and `c`): @@ -74,6 +73,8 @@ pub trait PartialEq { /// - reflexive: `a == a`; /// - symmetric: `a == b` implies `b == a`; and /// - transitive: `a == b` and `b == c` implies `a == c`. +/// +/// [equivalence relation]: https://en.wikipedia.org/wiki/Equivalence_relation #[unstable = "Definition may change slightly after trait reform"] pub trait Eq: PartialEq { // FIXME #13101: this method is used solely by #[deriving] to @@ -135,8 +136,7 @@ impl Ordering { } } -/// Trait for types that form a [total order]( -/// https://en.wikipedia.org/wiki/Total_order). +/// Trait for types that form a [total order] /// /// An order is a total order if it is (for all `a`, `b` and `c`): /// @@ -144,6 +144,8 @@ impl Ordering { /// true; and /// - transitive, `a < b` and `b < c` implies `a < c`. The same must hold for /// both `==` and `>`. +/// +/// [total order]: https://en.wikipedia.org/wiki/Total_order #[unstable = "Definition may change slightly after trait reform"] pub trait Ord: Eq + PartialOrd { /// This method returns an ordering between `self` and `other` values. diff --git a/src/libcore/lib.rs b/src/libcore/lib.rs index 7e2ea492d4ccf..547a3f85b32fc 100644 --- a/src/libcore/lib.rs +++ b/src/libcore/lib.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! # The Rust Core Library +//! The Rust Core Library //! //! The Rust Core Library is the dependency-free foundation of [The //! Rust Standard Library](../std/index.html). It is the portable glue diff --git a/src/librand/isaac.rs b/src/librand/isaac.rs index 0a857da92bbe4..758e449b41fa8 100644 --- a/src/librand/isaac.rs +++ b/src/librand/isaac.rs @@ -20,14 +20,14 @@ static RAND_SIZE_LEN: u32 = 8; static RAND_SIZE: u32 = 1 << (RAND_SIZE_LEN as uint); static RAND_SIZE_UINT: uint = 1 << (RAND_SIZE_LEN as uint); -/// A random number generator that uses the ISAAC algorithm[1]. +/// A random number generator that uses the [ISAAC] algorithm. /// /// The ISAAC algorithm is generally accepted as suitable for /// cryptographic purposes, but this implementation has not be /// verified as such. Prefer a generator like `OsRng` that defers to /// the operating system for cases that need high security. /// -/// [1]: Bob Jenkins, [*ISAAC: A fast cryptographic random number +/// [ISAAC]: Bob Jenkins, [*ISAAC: A fast cryptographic random number /// generator*](http://www.burtleburtle.net/bob/rand/isaacafa.html) pub struct IsaacRng { cnt: u32, @@ -254,7 +254,7 @@ impl Rand for IsaacRng { static RAND_SIZE_64_LEN: uint = 8; static RAND_SIZE_64: uint = 1 << RAND_SIZE_64_LEN; -/// A random number generator that uses ISAAC-64[1], the 64-bit +/// A random number generator that uses [ISAAC-64], the 64-bit /// variant of the ISAAC algorithm. /// /// The ISAAC algorithm is generally accepted as suitable for @@ -262,7 +262,7 @@ static RAND_SIZE_64: uint = 1 << RAND_SIZE_64_LEN; /// verified as such. Prefer a generator like `OsRng` that defers to /// the operating system for cases that need high security. /// -/// [1]: Bob Jenkins, [*ISAAC: A fast cryptographic random number +/// [ISAAC-64]: Bob Jenkins, [*ISAAC: A fast cryptographic random number /// generator*](http://www.burtleburtle.net/bob/rand/isaacafa.html) pub struct Isaac64Rng { cnt: uint, diff --git a/src/librand/lib.rs b/src/librand/lib.rs index f8a775478f1f8..2651a605d10f0 100644 --- a/src/librand/lib.rs +++ b/src/librand/lib.rs @@ -331,14 +331,13 @@ pub trait SeedableRng: Rng { fn from_seed(seed: Seed) -> Self; } -/// An Xorshift[1] random number -/// generator. +/// An [Xorshift] random number generator /// /// The Xorshift algorithm is not suitable for cryptographic purposes /// but is very fast. If you do not know for sure that it fits your /// requirements, use a more secure one such as `IsaacRng` or `OsRng`. /// -/// [1]: Marsaglia, George (July 2003). ["Xorshift +/// [Xorshift]: Marsaglia, George (July 2003). ["Xorshift /// RNGs"](http://www.jstatsoft.org/v08/i14/paper). *Journal of /// Statistical Software*. Vol. 8 (Issue 14). pub struct XorShiftRng { diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 299e41f72191d..ade0a3cde4b08 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! # The Rust Standard Library +//! The Rust Standard Library //! //! The Rust Standard Library provides the essential runtime //! functionality for building portable Rust software. diff --git a/src/libsyntax/ext/deriving/encodable.rs b/src/libsyntax/ext/deriving/encodable.rs index 103253560df65..06d455931c94e 100644 --- a/src/libsyntax/ext/deriving/encodable.rs +++ b/src/libsyntax/ext/deriving/encodable.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +//! Provides the Encodable and Decodable implementations +//! //! The compiler code necessary to implement the `#[deriving(Encodable)]` //! (and `Decodable`, in decodable.rs) extension. The idea here is that //! type-defining items may be tagged with `#[deriving(Encodable, Decodable)]`. diff --git a/src/libunicode/lib.rs b/src/libunicode/lib.rs index 239966cfd475d..5af4d0fb9fb23 100644 --- a/src/libunicode/lib.rs +++ b/src/libunicode/lib.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! # The Unicode Library +//! The Unicode Library //! //! Unicode-intensive functions for `char` and `str` types. //! From 5bd5e17140783c0f569f6f8f7b9ceac0260e3e6a Mon Sep 17 00:00:00 2001 From: Liigo Zhuang Date: Thu, 25 Sep 2014 08:28:32 +0800 Subject: [PATCH 2/4] move links in summery line to detail, and restore #s --- src/liballoc/lib.rs | 2 +- src/libcore/cmp.rs | 14 ++++++-------- src/libcore/lib.rs | 2 +- src/librand/isaac.rs | 12 ++++++------ src/librand/lib.rs | 6 +++--- src/libstd/lib.rs | 2 +- src/libunicode/lib.rs | 2 +- 7 files changed, 19 insertions(+), 21 deletions(-) diff --git a/src/liballoc/lib.rs b/src/liballoc/lib.rs index 641f7d90463a3..503c484e469d7 100644 --- a/src/liballoc/lib.rs +++ b/src/liballoc/lib.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! The Rust core allocation library +//! # The Rust core allocation library //! //! This is the lowest level library through which allocation in Rust can be //! performed where the allocation is assumed to succeed. This library will diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs index d6ff92c250bd4..9dd335caf02c1 100644 --- a/src/libcore/cmp.rs +++ b/src/libcore/cmp.rs @@ -65,16 +65,15 @@ pub trait PartialEq { fn ne(&self, other: &Self) -> bool { !self.eq(other) } } -/// Trait for equality comparisons which are [equivalence relation] +/// Trait for equality comparisons which are equivalence relation /// -/// This means, that in addition to `a == b` and `a != b` being strict +/// [Equivalence relation](https://en.wikipedia.org/wiki/Equivalence_relation) +/// means, that in addition to `a == b` and `a != b` being strict /// inverses, the equality must be (for all `a`, `b` and `c`): /// /// - reflexive: `a == a`; /// - symmetric: `a == b` implies `b == a`; and /// - transitive: `a == b` and `b == c` implies `a == c`. -/// -/// [equivalence relation]: https://en.wikipedia.org/wiki/Equivalence_relation #[unstable = "Definition may change slightly after trait reform"] pub trait Eq: PartialEq { // FIXME #13101: this method is used solely by #[deriving] to @@ -136,16 +135,15 @@ impl Ordering { } } -/// Trait for types that form a [total order] +/// Trait for types that form a total order /// -/// An order is a total order if it is (for all `a`, `b` and `c`): +/// An order is a [total order](https://en.wikipedia.org/wiki/Total_order) +/// if it is (for all `a`, `b` and `c`): /// /// - total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is /// true; and /// - transitive, `a < b` and `b < c` implies `a < c`. The same must hold for /// both `==` and `>`. -/// -/// [total order]: https://en.wikipedia.org/wiki/Total_order #[unstable = "Definition may change slightly after trait reform"] pub trait Ord: Eq + PartialOrd { /// This method returns an ordering between `self` and `other` values. diff --git a/src/libcore/lib.rs b/src/libcore/lib.rs index 547a3f85b32fc..7e2ea492d4ccf 100644 --- a/src/libcore/lib.rs +++ b/src/libcore/lib.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! The Rust Core Library +//! # The Rust Core Library //! //! The Rust Core Library is the dependency-free foundation of [The //! Rust Standard Library](../std/index.html). It is the portable glue diff --git a/src/librand/isaac.rs b/src/librand/isaac.rs index 758e449b41fa8..0820dc8435bcc 100644 --- a/src/librand/isaac.rs +++ b/src/librand/isaac.rs @@ -20,14 +20,14 @@ static RAND_SIZE_LEN: u32 = 8; static RAND_SIZE: u32 = 1 << (RAND_SIZE_LEN as uint); static RAND_SIZE_UINT: uint = 1 << (RAND_SIZE_LEN as uint); -/// A random number generator that uses the [ISAAC] algorithm. +/// A random number generator that uses the ISAAC algorithm. /// -/// The ISAAC algorithm is generally accepted as suitable for +/// The ISAAC algorithm[1] is generally accepted as suitable for /// cryptographic purposes, but this implementation has not be /// verified as such. Prefer a generator like `OsRng` that defers to /// the operating system for cases that need high security. /// -/// [ISAAC]: Bob Jenkins, [*ISAAC: A fast cryptographic random number +/// [1]: Bob Jenkins, [*ISAAC: A fast cryptographic random number /// generator*](http://www.burtleburtle.net/bob/rand/isaacafa.html) pub struct IsaacRng { cnt: u32, @@ -254,15 +254,15 @@ impl Rand for IsaacRng { static RAND_SIZE_64_LEN: uint = 8; static RAND_SIZE_64: uint = 1 << RAND_SIZE_64_LEN; -/// A random number generator that uses [ISAAC-64], the 64-bit +/// A random number generator that uses ISAAC-64, the 64-bit /// variant of the ISAAC algorithm. /// -/// The ISAAC algorithm is generally accepted as suitable for +/// The ISAAC algorithm[1] is generally accepted as suitable for /// cryptographic purposes, but this implementation has not be /// verified as such. Prefer a generator like `OsRng` that defers to /// the operating system for cases that need high security. /// -/// [ISAAC-64]: Bob Jenkins, [*ISAAC: A fast cryptographic random number +/// [1]: Bob Jenkins, [*ISAAC: A fast cryptographic random number /// generator*](http://www.burtleburtle.net/bob/rand/isaacafa.html) pub struct Isaac64Rng { cnt: uint, diff --git a/src/librand/lib.rs b/src/librand/lib.rs index 2651a605d10f0..a90885792570e 100644 --- a/src/librand/lib.rs +++ b/src/librand/lib.rs @@ -331,13 +331,13 @@ pub trait SeedableRng: Rng { fn from_seed(seed: Seed) -> Self; } -/// An [Xorshift] random number generator +/// An Xorshift random number generator /// -/// The Xorshift algorithm is not suitable for cryptographic purposes +/// The Xorshift algorithm[1] is not suitable for cryptographic purposes /// but is very fast. If you do not know for sure that it fits your /// requirements, use a more secure one such as `IsaacRng` or `OsRng`. /// -/// [Xorshift]: Marsaglia, George (July 2003). ["Xorshift +/// [1]: Marsaglia, George (July 2003). ["Xorshift /// RNGs"](http://www.jstatsoft.org/v08/i14/paper). *Journal of /// Statistical Software*. Vol. 8 (Issue 14). pub struct XorShiftRng { diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index ade0a3cde4b08..299e41f72191d 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! The Rust Standard Library +//! # The Rust Standard Library //! //! The Rust Standard Library provides the essential runtime //! functionality for building portable Rust software. diff --git a/src/libunicode/lib.rs b/src/libunicode/lib.rs index 5af4d0fb9fb23..239966cfd475d 100644 --- a/src/libunicode/lib.rs +++ b/src/libunicode/lib.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! The Unicode Library +//! # The Unicode Library //! //! Unicode-intensive functions for `char` and `str` types. //! From 8ea4daa008b47071a16268bc5c739d884bbf49a5 Mon Sep 17 00:00:00 2001 From: Liigo Zhuang Date: Thu, 25 Sep 2014 09:29:03 +0800 Subject: [PATCH 3/4] more cleanup --- src/libflate/lib.rs | 10 ++++++---- src/libgraphviz/lib.rs | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/src/libflate/lib.rs b/src/libflate/lib.rs index 4226ac14118a4..3e38c9ae1e478 100644 --- a/src/libflate/lib.rs +++ b/src/libflate/lib.rs @@ -10,11 +10,13 @@ /*! -Simple [DEFLATE][def]-based compression. This is a wrapper around the -[`miniz`][mz] library, which is a one-file pure-C implementation of zlib. +Simple DEFLATE-based compression -[def]: https://en.wikipedia.org/wiki/DEFLATE -[mz]: https://code.google.com/p/miniz/ +[DEFLATE](https://en.wikipedia.org/wiki/DEFLATE) is a data compression +algorithm that uses a combination of the LZ77 algorithm and Huffman coding. + +This crate is a wrapper around the [miniz](https://code.google.com/p/miniz/) +library, which is a one-file pure-C implementation of zlib. */ diff --git a/src/libgraphviz/lib.rs b/src/libgraphviz/lib.rs index 19f58a210d00b..3fc8aa0cd5f3d 100644 --- a/src/libgraphviz/lib.rs +++ b/src/libgraphviz/lib.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! Generate files suitable for use with [Graphviz](http://www.graphviz.org/) +/*! Generate files suitable for use with Graphviz The `render` function generates output (e.g. an `output.dot` file) for use with [Graphviz](http://www.graphviz.org/) by walking a labelled From 125c7f98e8f39742f9c3435c23f9d49d407bf647 Mon Sep 17 00:00:00 2001 From: Liigo Zhuang Date: Thu, 25 Sep 2014 09:50:42 +0800 Subject: [PATCH 4/4] and more --- src/libcore/cmp.rs | 6 +++--- src/libunicode/u_str.rs | 5 +++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs index 9dd335caf02c1..d00c98733fcb6 100644 --- a/src/libcore/cmp.rs +++ b/src/libcore/cmp.rs @@ -92,11 +92,11 @@ pub trait Eq: PartialEq { #[deriving(Clone, PartialEq, Show)] #[stable] pub enum Ordering { - /// An ordering where a compared value is less [than another]. + /// An ordering where a compared value is less (than another) Less = -1i, - /// An ordering where a compared value is equal [to another]. + /// An ordering where a compared value is equal (to another) Equal = 0i, - /// An ordering where a compared value is greater [than another]. + /// An ordering where a compared value is greater (than another) Greater = 1i, } diff --git a/src/libunicode/u_str.rs b/src/libunicode/u_str.rs index 88f9c2b4ce39d..b1400a218f4dc 100644 --- a/src/libunicode/u_str.rs +++ b/src/libunicode/u_str.rs @@ -198,8 +198,9 @@ impl<'a> DoubleEndedIterator<(uint, &'a str)> for GraphemeIndices<'a> { } } -/// External iterator for a string's -/// [grapheme clusters](http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries). +/// External iterator for a string's grapheme clusters +/// +/// http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries #[deriving(Clone)] pub struct Graphemes<'a> { string: &'a str,