www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 23270] New: std.random.dice is poorly documented


          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 puremagic.com
          Reporter: desisma 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 --
Jul 23 2022