[Issue 23270] New: std.random.dice is poorly documented

[d-bugmail at puremagic.com]

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: nobody at puremagic.com
          Reporter: desisma at 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

--