https://issues.dlang.org/show_bug.cgi?id=23270
Issue ID: 23270
Summary: std.random.dice is poorly documented
Product: D
Version: D2
Hardware: All
OS: All
Status: NEW
Severity: minor
Priority: P1
Component: phobos
Assignee: nob...@puremagic.com
Reporter: desi...@heidel.beer
Documentation of std.random.dice is very poor.
I’ve used that function in the past, yet had to read through it a few times to
get how it workes.
to be honest, my first thought after reading it for the first time was like:
> Has the author ever held a dice in their hand!?
Let me elaborate:
A real-world dice, mathematically called a «fair dice», is usually labelled
1,2,3,4,5,6; where each side has the very same probability (1÷6).
The first number mentioned in the documentation is «0.5». That’s kinda
unexpected.
Neither 50-50, 70 or 42 (you can find all of them in the docs) is what I’d
expect either.
The first example should be how to code a real-world-alike «fair dice» with
numbers 1 … 6.
Feel free to explain the advanced stuff afterwards.
But keep in mind: It does *not* reassemble a real world dice…
Paul Backus on Discord about this matter:
> Literally the worst-named function in Phobos.
> It should be called something lime `weightedChoice`.
> As you’ve noticed, it has noting at all to do with dice
- Elias
--
