Skip to content
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.

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

Remove rand os example #60

Merged
merged 2 commits into from
Aug 18, 2020
Merged

Remove rand os example #60

merged 2 commits into from
Aug 18, 2020

Conversation

hdevalence
Copy link
Contributor

Closes #59.

The doc examples have code interspersed with text explaining the API. Because
each doctest executes independently, when these code examples are run as
doctests, they have to include parts of the previous examples with # lines.
These lines are hidden from Rustdoc output and do not appear in the rendered
docs, but they do appear when viewing the README.md on Github.

In order to hide these on Github, the code blocks were made non-executable,
with their content moved to a unit test. However, this meant that the example
API usage was not tested, and so when the unit test was updated to remove the
deprecated rand_os, there was no check that the examples stayed in sync with
the test, causing #59. To prevent this from reocurring in the future, go back
to executable tests of the API examples.

`rand_core` defines a blanket impl of `RngCore + CryptoRng` for `&mut T` where
`T: RngCore + CryptoRng`, so rather than requiring a borrowed RNG, it's better
to require an owned RNG, as this allows passing either owned or borrowed
values.  In particular, this makes `OsRng` usage much more ergonomic, because
the caller is not forced to do `&mut OsRng` on the zero-sized struct.
Closes #59.

The doc examples have code interspersed with text explaining the API.  Because
each doctest executes independently, when these code examples are run as
doctests, they have to include parts of the previous examples with # lines.
These lines are hidden from Rustdoc output and do not appear in the rendered
docs, but they do appear when viewing the README.md on Github.

In order to hide these on Github, the code blocks were made non-executable,
with their content moved to a unit test.  However, this meant that the example
API usage was not tested, and so when the unit test was updated to remove the
deprecated `rand_os`, there was no check that the examples stayed in sync with
the test, causing #59.  To prevent this from reocurring in the future, go back
to executable tests of the API examples.
@hdevalence hdevalence merged commit 736f8dd into develop Aug 18, 2020
@hdevalence hdevalence deleted the remove-rand-os-example branch August 18, 2020 02:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants