Use RFC 1946 for doc links

Author: newpavlov

rand_chacha/src/chacha.rs

@@ -62,10 +62,8 @@ const STATE_WORDS: usize = 16;
 /// [^2]: [eSTREAM: the ECRYPT Stream Cipher Project](
 ///       http://www.ecrypt.eu.org/stream/)
 ///
-/// [`set_word_pos`]: #method.set_word_pos
-/// [`set_stream`]: #method.set_stream
-/// [`BlockRng`]: ../rand_core/block/struct.BlockRng.html
-/// [`RngCore`]: ../rand_core/trait.RngCore.html
+/// [`set_word_pos`]: ChaChaRng::set_word_pos
+/// [`set_stream`]: ChaChaRng::set_stream
 #[derive(Clone, Debug)]
 pub struct ChaChaRng(BlockRng<ChaChaCore>);
 

rand_core/src/block.rs

@@ -16,7 +16,8 @@
 //! implementations only need to concern themselves with generation of the
 //! block, not the various [`RngCore`] methods (especially [`fill_bytes`], where
 //! the optimal implementations are not trivial), and this allows
-//! [`ReseedingRng`] perform periodic reseeding with very low overhead.
+//! `ReseedingRng` (see [`rand`](https://docs.rs/rand) crate) perform periodic
+//! reseeding with very low overhead.
 //!
 //! # Example
 //! 
@@ -46,10 +47,8 @@
 //! type MyRng = BlockRng<u32, MyRngCore>;
 //! ```
 //! 
-//! [`BlockRngCore`]: trait.BlockRngCore.html
-//! [`RngCore`]: ../trait.RngCore.html
-//! [`fill_bytes`]: ../trait.RngCore.html#tymethod.fill_bytes
-//! [`ReseedingRng`]: ../../rand/rngs/adapter/struct.ReseedingRng.html
+//! [`BlockRngCore`]: crate::block::BlockRngCore
+//! [`fill_bytes`]: RngCore::fill_bytes
 
 use core::convert::AsRef;
 use core::fmt;
@@ -60,7 +59,7 @@ use impls::{fill_via_u32_chunks, fill_via_u64_chunks};
 /// blocks (typically `[u32; N]`). This technique is commonly used by
 /// cryptographic RNGs to improve performance.
 /// 
-/// See the [module documentation](index.html) for details.
+/// See the [module][crate::block] documentation for details.
 pub trait BlockRngCore {
     /// Results element type, e.g. `u32`.
     type Item;
@@ -105,15 +104,10 @@ pub trait BlockRngCore {
 ///
 /// For easy initialization `BlockRng` also implements [`SeedableRng`].
 ///
-/// [`BlockRngCore`]: BlockRngCore.t.html
-/// [`BlockRngCore::generate`]: trait.BlockRngCore.html#tymethod.generate
-/// [`BlockRng64`]: struct.BlockRng64.html
-/// [`RngCore`]: ../RngCore.t.html
-/// [`next_u32`]: ../trait.RngCore.html#tymethod.next_u32
-/// [`next_u64`]: ../trait.RngCore.html#tymethod.next_u64
-/// [`fill_bytes`]: ../trait.RngCore.html#tymethod.fill_bytes
-/// [`try_fill_bytes`]: ../trait.RngCore.html#tymethod.try_fill_bytes
-/// [`SeedableRng`]: ../SeedableRng.t.html
+/// [`next_u32`]: RngCore::next_u32
+/// [`next_u64`]: RngCore::next_u64
+/// [`fill_bytes`]: RngCore::fill_bytes
+/// [`try_fill_bytes`]: RngCore::try_fill_bytes
 #[derive(Clone)]
 #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]
 pub struct BlockRng<R: BlockRngCore + ?Sized> {
@@ -314,13 +308,10 @@ impl<R: BlockRngCore + SeedableRng> SeedableRng for BlockRng<R> {
 /// values. If the requested length is not a multiple of 8, some bytes will be
 /// discarded.
 ///
-/// [`BlockRngCore`]: BlockRngCore.t.html
-/// [`RngCore`]: ../RngCore.t.html
-/// [`next_u32`]: ../trait.RngCore.html#tymethod.next_u32
-/// [`next_u64`]: ../trait.RngCore.html#tymethod.next_u64
-/// [`fill_bytes`]: ../trait.RngCore.html#tymethod.fill_bytes
-/// [`try_fill_bytes`]: ../trait.RngCore.html#tymethod.try_fill_bytes
-/// [`BlockRng`]: struct.BlockRng.html
+/// [`next_u32`]: RngCore::next_u32
+/// [`next_u64`]: RngCore::next_u64
+/// [`fill_bytes`]: RngCore::fill_bytes
+/// [`try_fill_bytes`]: RngCore::try_fill_bytes
 #[derive(Clone)]
 #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]
 pub struct BlockRng64<R: BlockRngCore + ?Sized> {

rand_core/src/lib.rs

@@ -10,7 +10,7 @@
 //! Random number generation traits
 //! 
 //! This crate is mainly of interest to crates publishing implementations of
-//! [`RngCore`]. Other users are encouraged to use the [rand] crate instead
+//! [`RngCore`]. Other users are encouraged to use the [`rand`] crate instead
 //! which re-exports the main traits and error types.
 //!
 //! [`RngCore`] is the core trait implemented by algorithmic pseudo-random number
@@ -25,12 +25,7 @@
 //! The [`impls`] and [`le`] sub-modules include a few small functions to assist
 //! implementation of [`RngCore`].
 //! 
-//! [rand]: https://crates.io/crates/rand
-//! [`RngCore`]: trait.RngCore.html
-//! [`SeedableRng`]: trait.SeedableRng.html
-//! [`Error`]: struct.Error.html
-//! [`impls`]: impls/index.html
-//! [`le`]: le/index.html
+//! [`rand`]: https://docs.rs/rand
 
 #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
        html_favicon_url = "https://www.rust-lang.org/favicon.ico",
@@ -68,8 +63,8 @@ pub mod le;
 /// 
 /// This trait encapsulates the low-level functionality common to all
 /// generators, and is the "back end", to be implemented by generators.
-/// End users should normally use [`Rng`] from the [rand] crate, which is
-/// automatically implemented for every type implementing `RngCore`.
+/// End users should normally use `Rng` trait from the [`rand`] crate,
+/// which is automatically implemented for every type implementing `RngCore`.
 /// 
 /// Three different methods for generating random data are provided since the
 /// optimal implementation of each is dependent on the type of generator. There
@@ -89,7 +84,7 @@ pub mod le;
 /// 
 /// Typically implementators will implement only one of the methods available
 /// in this trait directly, then use the helper functions from the
-/// [`rand_core::impls`] module to implement the other methods.
+/// [`impls`] module to implement the other methods.
 /// 
 /// It is recommended that implementations also implement:
 /// 
@@ -135,40 +130,37 @@ pub mod le;
 /// }
 /// ```
 /// 
-/// [rand]: https://crates.io/crates/rand
-/// [`Rng`]: ../rand/trait.Rng.html
-/// [`SeedableRng`]: trait.SeedableRng.html
-/// [`rand_core::impls`]: ../rand_core/impls/index.html
-/// [`try_fill_bytes`]: trait.RngCore.html#tymethod.try_fill_bytes
-/// [`fill_bytes`]: trait.RngCore.html#tymethod.fill_bytes
-/// [`next_u32`]: trait.RngCore.html#tymethod.next_u32
-/// [`next_u64`]: trait.RngCore.html#tymethod.next_u64
-/// [`CryptoRng`]: trait.CryptoRng.html
+/// [`rand`]: https://docs.rs/rand
+/// [`try_fill_bytes`]: RngCore::try_fill_bytes
+/// [`fill_bytes`]: RngCore::fill_bytes
+/// [`next_u32`]: RngCore::next_u32
+/// [`next_u64`]: RngCore::next_u64
 pub trait RngCore {
     /// Return the next random `u32`.
     ///
     /// RNGs must implement at least one method from this trait directly. In
     /// the case this method is not implemented directly, it can be implemented
-    /// using `self.next_u64() as u32` or
-    /// [via `fill_bytes`](../rand_core/impls/fn.next_u32_via_fill.html).
+    /// using `self.next_u64() as u32` or via
+    /// [`fill_bytes`][impls::next_u32_via_fill].
     fn next_u32(&mut self) -> u32;
 
     /// Return the next random `u64`.
     ///
     /// RNGs must implement at least one method from this trait directly. In
     /// the case this method is not implemented directly, it can be implemented
-    /// [via `next_u32`](../rand_core/impls/fn.next_u64_via_u32.html) or
-    /// [via `fill_bytes`](../rand_core/impls/fn.next_u64_via_fill.html).
+    /// via [`next_u32`][impls::next_u64_via_u32] or via 
+    /// [`fill_bytes`][impls::next_u64_via_fill].
     fn next_u64(&mut self) -> u64;
 
     /// Fill `dest` with random data.
     ///
     /// RNGs must implement at least one method from this trait directly. In
     /// the case this method is not implemented directly, it can be implemented
-    /// [via `next_u*`](../rand_core/impls/fn.fill_bytes_via_next.html) or
-    /// via `try_fill_bytes`; if this generator can fail the implementation
-    /// must choose how best to handle errors here (e.g. panic with a
-    /// descriptive message or log a warning and retry a few times).
+    /// via [`next_u*`][impls::fill_bytes_via_next] or
+    /// via [`try_fill_bytes`][RngCore::try_fill_bytes]; if this generator can
+    /// fail the implementation must choose how best to handle errors here
+    /// (e.g. panic with a descriptive message or log a warning and retry a few
+    /// times).
     /// 
     /// This method should guarantee that `dest` is entirely filled
     /// with new data, and may panic if this is impossible
@@ -188,7 +180,7 @@ pub trait RngCore {
     /// `fill_bytes` may be implemented with
     /// `self.try_fill_bytes(dest).unwrap()` or more specific error handling.
     /// 
-    /// [`fill_bytes`]: trait.RngCore.html#method.fill_bytes
+    /// [`fill_bytes`]: RngCore::fill_bytes
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>;
 }
 
@@ -213,20 +205,19 @@ pub trait RngCore {
 /// Note also that use of a `CryptoRng` does not protect against other
 /// weaknesses such as seeding from a weak entropy source or leaking state.
 /// 
-/// [`RngCore`]: trait.RngCore.html
-/// [`BlockRngCore`]: ../rand_core/block/trait.BlockRngCore.html
+/// [`BlockRngCore`]: block::BlockRngCore
 pub trait CryptoRng {}
 
 /// A random number generator that can be explicitly seeded.
 ///
 /// This trait encapsulates the low-level functionality common to all
 /// pseudo-random number generators (PRNGs, or algorithmic generators).
 /// 
-/// The [`rand::FromEntropy`] trait is automatically implemented for every type
-/// implementing `SeedableRng`, providing a convenient `from_entropy()`
-/// constructor.
+/// The `FromEntropy` trait from [`rand`] crate is automatically
+/// implemented for every type implementing `SeedableRng`, providing
+/// a convenient `from_entropy()` constructor.
 /// 
-/// [`rand::FromEntropy`]: ../rand/trait.FromEntropy.html
+/// [`rand`]: https://docs.rs/rand
 pub trait SeedableRng: Sized {
     /// Seed type, which is restricted to types mutably-dereferencable as `u8`
     /// arrays (we recommend `[u8; N]` for some `N`).
@@ -340,8 +331,8 @@ pub trait SeedableRng: Sized {
     /// Create a new PRNG seeded from another `Rng`.
     ///
     /// This is the recommended way to initialize PRNGs with fresh entropy. The
-    /// [`FromEntropy`] trait provides a convenient `from_entropy` method
-    /// based on `from_rng`.
+    /// `FromEntropy` trait from [`rand`] crate provides a convenient
+    /// `from_entropy` method based on `from_rng`.
     /// 
     /// Usage of this method is not recommended when reproducibility is required
     /// since implementing PRNGs are not required to fix Endianness and are
@@ -354,9 +345,9 @@ pub trait SeedableRng: Sized {
     /// results if their seed numbers are small or if there is a simple pattern
     /// between them.
     ///
-    /// Prefer to seed from a strong external entropy source like [`OsRng`] or
-    /// from a cryptographic PRNG; if creating a new generator for cryptographic
-    /// uses you *must* seed from a strong source.
+    /// Prefer to seed from a strong external entropy source like `OsRng` from
+    /// [`rand_os`] crate or from a cryptographic PRNG; if creating a new
+    /// generator for cryptographic uses you *must* seed from a strong source.
     ///
     /// Seeding a small PRNG from another small PRNG is possible, but
     /// something to be careful with. An extreme example of how this can go
@@ -367,8 +358,8 @@ pub trait SeedableRng: Sized {
     /// PRNG implementations are allowed to assume that a good RNG is provided
     /// for seeding, and that it is cryptographically secure when appropriate.
     /// 
-    /// [`FromEntropy`]: ../rand/trait.FromEntropy.html
-    /// [`OsRng`]: ../rand/rngs/struct.OsRng.html
+    /// [`rand`]: https://docs.rs/rand
+    /// [`rand_os`]: https://docs.rs/rand_os
     fn from_rng<R: RngCore>(mut rng: R) -> Result<Self, Error> {
         let mut seed = Self::Seed::default();
         rng.try_fill_bytes(seed.as_mut())?;

rand_hc/src/hc128.rs

@@ -63,9 +63,6 @@ const SEED_WORDS: usize = 8; // 128 bit key followed by 128 bit iv
 ///
 /// [^5]: Internet Engineering Task Force (February 2015),
 ///       ["Prohibiting RC4 Cipher Suites"](https://tools.ietf.org/html/rfc7465).
-///
-/// [`BlockRng`]: ../rand_core/block/struct.BlockRng.html
-/// [`RngCore`]: ../rand_core/trait.RngCore.html
 #[derive(Clone, Debug)]
 pub struct Hc128Rng(BlockRng<Hc128Core>);
 

rand_isaac/src/isaac.rs

@@ -34,8 +34,8 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 /// In spite of being designed with cryptographic security in mind, ISAAC hasn't
 /// been stringently cryptanalyzed and thus cryptographers do not not
 /// consensually trust it to be secure. When looking for a secure RNG, prefer
-/// [`Hc128Rng`] instead, which, like ISAAC, is an array-based RNG and one of
-/// the stream-ciphers selected the by eSTREAM contest.
+/// `Hc128Rng` from [`rand_hc`] crate instead, which, like ISAAC, is an
+/// array-based RNG and one of the stream-ciphers selected the by eSTREAM 
 ///
 /// In 2006 an improvement to ISAAC was suggested by Jean-Philippe Aumasson,
 /// named ISAAC+[^3]. But because the specification is not complete, because
@@ -86,9 +86,7 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 /// [^3]: Jean-Philippe Aumasson, [*On the pseudo-random generator ISAAC*](
 ///       https://eprint.iacr.org/2006/438)
 ///
-/// [`Hc128Rng`]: ../../rand_hc/struct.Hc128Rng.html
-/// [`BlockRng`]: ../../rand_core/block/struct.BlockRng.html
-/// [`RngCore`]: ../../rand_core/trait.RngCore.html
+/// [`rand_hc`]: https://docs.rs/rand_hc
 #[derive(Clone, Debug)]
 #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]
 pub struct IsaacRng(BlockRng<IsaacCore>);
@@ -142,7 +140,7 @@ impl IsaacRng {
     }
 }
 
-/// The core of `IsaacRng`, used with `BlockRng`.
+/// The core of [`IsaacRng`], used with [`BlockRng`].
 #[derive(Clone)]
 #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]
 pub struct IsaacCore {
@@ -165,7 +163,7 @@ impl BlockRngCore for IsaacCore {
     type Results = IsaacArray<Self::Item>;
 
     /// Refills the output buffer, `results`. See also the pseudocode desciption
-    /// of the algorithm in the [`IsaacRng`] documentation.
+    /// of the algorithm in the `IsaacRng` documentation.
     ///
     /// Optimisations used (similar to the reference implementation):
     /// 
@@ -183,8 +181,6 @@ impl BlockRngCore for IsaacCore {
     ///   from `results` in reverse. We read them in the normal direction, to
     ///   make `fill_bytes` a memcopy. To maintain compatibility we fill in
     ///   reverse.
-    /// 
-    /// [`IsaacRng`]: struct.IsaacRng.html
     fn generate(&mut self, results: &mut IsaacArray<Self::Item>) {
         self.c += w(1);
         // abbreviations

rand_isaac/src/isaac64.rs

@@ -40,8 +40,8 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 /// In spite of being designed with cryptographic security in mind, ISAAC hasn't
 /// been stringently cryptanalyzed and thus cryptographers do not not
 /// consensually trust it to be secure. When looking for a secure RNG, prefer
-/// [`Hc128Rng`] instead, which, like ISAAC, is an array-based RNG and one of
-/// the stream-ciphers selected the by eSTREAM contest.
+/// `Hc128Rng` from [`rand_hc`] crate instead, which, like ISAAC, is an
+/// array-based RNG and one of the stream-ciphers selected the by eSTREAM 
 ///
 /// ## Overview of the ISAAC-64 algorithm:
 /// (in pseudo-code)
@@ -75,10 +75,9 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 /// [^1]: Bob Jenkins, [*ISAAC and RC4*](
 ///       http://burtleburtle.net/bob/rand/isaac.html)
 ///
-/// [`IsaacRng`]: ../isaac/struct.IsaacRng.html
-/// [`Hc128Rng`]: ../../rand_hc/struct.Hc128Rng.html
-/// [`BlockRng64`]: ../../rand_core/block/struct.BlockRng64.html
-/// [`RngCore`]: ../../rand_core/trait.RngCore.html
+/// [`IsaacRng`]: crate::isaac::IsaacRng
+/// [`rand_hc`]: https://docs.rs/rand_hc
+/// [`BlockRng64`]: rand_core::block::BlockRng64
 #[derive(Clone, Debug)]
 #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]
 pub struct Isaac64Rng(BlockRng64<Isaac64Core>);
@@ -155,7 +154,7 @@ impl BlockRngCore for Isaac64Core {
     type Results = IsaacArray<Self::Item>;
 
     /// Refills the output buffer, `results`. See also the pseudocode desciption
-    /// of the algorithm in the [`Isaac64Rng`] documentation.
+    /// of the algorithm in the `Isaac64Rng` documentation.
     ///
     /// Optimisations used (similar to the reference implementation):
     /// 
@@ -173,8 +172,6 @@ impl BlockRngCore for Isaac64Core {
     ///   from `results` in reverse. We read them in the normal direction, to
     ///   make `fill_bytes` a memcopy. To maintain compatibility we fill in
     ///   reverse.
-    /// 
-    /// [`Isaac64Rng`]: struct.Isaac64Rng.html
     fn generate(&mut self, results: &mut IsaacArray<Self::Item>) {
         self.c += w(1);
         // abbreviations

rand_os/src/lib.rs

@@ -9,15 +9,15 @@
 
 //! Interface to the random number generator of the operating system.
 //!
-//! `OsRng` is the preferred external source of entropy for most applications.
+//! [`OsRng`] is the preferred external source of entropy for most applications.
 //! Commonly it is used to initialize a user-space RNG, which can then be used
 //! to generate random values with much less overhead than `OsRng`.
 //!
 //! You may prefer to use [`EntropyRng`] instead of `OsRng`. It is unlikely, but
 //! not entirely theoretical, for `OsRng` to fail. In such cases [`EntropyRng`]
 //! falls back on a good alternative entropy source.
 //!
-//! `OsRng::new()` is guaranteed to be very cheap (after the first successful
+//! [`OsRng::new()`] is guaranteed to be very cheap (after the first successful
 //! call), and will never consume more than one file handle per process.
 //!
 //! # Usage example
@@ -100,9 +100,8 @@
 //! but must eventually panic if the error persists.
 //!
 //! [`EntropyRng`]: ../rand/rngs/struct.EntropyRng.html
-//! [`RngCore`]: ../rand_core/trait.RngCore.html
-//! [`try_fill_bytes`]: ../rand_core/trait.RngCore.html#method.tymethod.try_fill_bytes
-//! [`ErrorKind::NotReady`]: ../rand_core/enum.ErrorKind.html#variant.NotReady
+//! [`try_fill_bytes`]: RngCore::try_fill_bytes
+//! [`ErrorKind::NotReady`]: rand_core::ErrorKind
 //!
 //! [1]: http://man7.org/linux/man-pages/man2/getrandom.2.html
 //! [2]: http://man7.org/linux/man-pages/man4/urandom.4.html