cleanup summery line docs

src/libcore/cmp.rs

@@ -65,10 +65,10 @@ 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
+/// [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`;
@@ -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,
 }
 
@@ -135,10 +135,10 @@ 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`):
+/// 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

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.
 
 */
 

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

src/librand/isaac.rs

@@ -20,9 +20,9 @@ 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
+/// 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.
@@ -254,10 +254,10 @@ 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
+/// 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.

src/librand/lib.rs

@@ -331,10 +331,9 @@ pub trait SeedableRng<Seed>: 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
+/// 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`.
 ///

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)]`.

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,