Skip to content

Use RFC 1946 for doc links #691

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 14, 2019
Merged

Use RFC 1946 for doc links #691

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b451306
Use RFC 1946 for doc links
newpavlov Jan 11, 2019
300b84b
fix errors
newpavlov Jan 14, 2019
b72b6ae
fix errors
newpavlov Jan 14, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions rand_chacha/src/chacha.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>);

Expand Down
57 changes: 24 additions & 33 deletions rand_core/src/block.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,40 +16,39 @@
//! 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is my second point in #690. I don't much like it — it depends on docs.rs and even so isn't a direct link — but I guess it's one option.

I would prefer such a link point to the crates.io page, possibly with a second link pointing to the API docs, or as discussed in rust-lang/docs.rs#204, be a direct link like [rand::rngs::adapter::ReseedingRng] (unfortunately I cannot get this to work).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally I would like to [rand::rngs::adapter::ReseedingRng] (or something similar) to work , but AFAIK there is currently no good way to do it except absolute links. So I think it's alright to use docs.rs links as a temporary solution, which will be easy to replace in future.

//!
//! # Example
//!
//!
//! ```norun
//! use rand_core::block::{BlockRngCore, BlockRng};
//!
//!
//! struct MyRngCore;
//!
//!
//! impl BlockRngCore for MyRngCore {
//! type Results = [u32; 16];
//!
//!
//! fn generate(&mut self, results: &mut Self::Results) {
//! unimplemented!()
//! }
//! }
//!
//!
//! impl SeedableRng for MyRngCore {
//! type Seed = unimplemented!();
//! fn from_seed(seed: Self::Seed) -> Self {
//! unimplemented!()
//! }
//! }
//!
//!
//! // optionally, also implement CryptoRng for MyRngCore
//!
//!
//! // Final RNG.
//! 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So items from the crate root (RngCore) get auto-linked but not those from the same module (BlockRngCore)?

Copy link
Member Author

@newpavlov newpavlov Jan 13, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it's a weird restriction, you can reference imported items, but not defined in the current module. It probably deserves a rustdoc issue.

//! [`fill_bytes`]: RngCore::fill_bytes

use core::convert::AsRef;
use core::fmt;
Expand All @@ -59,12 +58,12 @@ use impls::{fill_via_u32_chunks, fill_via_u64_chunks};
/// A trait for RNGs which do not generate random numbers individually, but in
/// 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;

/// Results type. This is the 'block' an RNG implementing `BlockRngCore`
/// generates, which will usually be an array like `[u32; 16]`.
type Results: AsRef<[Self::Item]> + AsMut<[Self::Item]> + Default;
Expand Down Expand Up @@ -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> {
Expand Down Expand Up @@ -147,7 +141,7 @@ impl<R: BlockRngCore> BlockRng<R> {
}

/// Get the index into the result buffer.
///
///
/// If this is equal to or larger than the size of the result buffer then
/// the buffer is "empty" and `generate()` must be called to produce new
/// results.
Expand Down Expand Up @@ -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> {
Expand Down
Loading