Random: document the Sampler machinery #27983
Conversation
rfourquet
added
docs
|
This is in better shape now (though not yet ideal) and ready for review. Note that in 1 example ( |
rfourquet
changed the title
|
Is it expected that circleci is "pending" for many hours (almost one day). Also I don't really understand Appveyor failures, could someone have a look and confirm that these are not related to this PR? |
|
Download is shaky lately, and also #27982. Doesn't seem related. |
|
Ok thank you for having a look! Given that it's only a documentation PR, re-running the tests only for appveyor seems unnecessary, when (if I understood correctly) doctests are mostly run on travis. This is good to go for me, feel free to merge. |
stdlib/Random/docs/src/index.md
Outdated
| struct Die | ||
| nsides::Int # number of sides | ||
| end | ||
|
|
There was a problem hiding this comment.
IMO we should add
using Random
to prevent deprecations warning
There was a problem hiding this comment.
I think a bunch of stdlib modules assume an implicit corresponding using directive...
stdlib/Random/docs/src/index.md
Outdated
| Let's take the following example: we implement a `Die` type, with a variable number `n` of sides, numbered from `1` to `n`. | ||
| We want `rand(Die)` to produce a die with a random number of up to 20 sides (and at least 4): | ||
|
|
||
| ```julia |
There was a problem hiding this comment.
Can this plus code below be doctests?
There was a problem hiding this comment.
I will see what I can do. What I find slightly annoying for rand examples is that you have to explicitly use srand, but not a big deal. Also, I was not clear how to re-use a definition in block into another block, but IIRC, it's quite easy.
There was a problem hiding this comment.
You can call srand in a setup block e.g.
```jldoctest; setup = :(using Random; srand(1234))
julia> rand()
1.2
```
stdlib/Random/docs/src/index.md
Outdated
| `rand(rng::AbstractRNG, sp::Random.SamplerTrivial{T})`. Here, `sp` simply wraps an object of type `T`, which can be accessed via `sp[]`. | ||
| Continuing the `Die` example, we want now to define `rand(d::Die)` to produce an `Int` corresponding to one of `d`'s sides: | ||
|
|
||
| ```julia-repl |
stdlib/Random/docs/src/index.md
Outdated
|
|
||
| #### Generating values from a collection | ||
|
|
||
| Given a collection type `T`, it's currently assumed that if `rand(::T)` is defined, an object of type `eltype(T)` will be produced. |
There was a problem hiding this comment.
Is it worth using another letter than T here to not mix it up with the T earlier used?
There was a problem hiding this comment.
It appears sufficiently far from the other T, but if you give me a new name for here, I will use it.
stdlib/Random/docs/src/index.md
Outdated
| ```@meta | ||
| DocTestSetup = nothing | ||
| DocTestSetup = :(using Random) |
There was a problem hiding this comment.
I found it at the end of the file, so left it there.
There was a problem hiding this comment.
But why change nothing to using Random?
There was a problem hiding this comment.
I saw this practice in another stdlib and assumed this would be necessary for doctests... I guess I was planing on making doctests at that time ;-)
There was a problem hiding this comment.
Well, we have this setup with using Random at the top of this file, and here at the bottom we want to reset it, so we put it to nothing.
There was a problem hiding this comment.
oups!! embarassing, will fix
|
Added |
This is a first draft which is not ready for review, but I thought I would still share it for potential eager reviewers.
I will have very little time in the next few weeks, so my plan is to merge this by the middle of next week to support upgradathon, and work on possible improvements later.
Fixes #25605.