The Random docs skip over the hardest part ..and other doubts

• The docs for std.Random do not include a working example; ie if you concat the snippets on the page, it will not compile. And on closer inspection, you'll discover that the missing part is omitted from the docs not because it's too trivial to mention, but rather because it's the most difficult piece!

The problem lies in the section "Creating a Random instance".

Obtaining an instance of Random can be as simple as:

import cats.effect.IO
import cats.effect.std.Random

Random.scalaUtilRandom[IO]

Unfortunately, the user will discover that creating a random instance is not so simple at all. The expression given is of type IO[Random[IO]], so that's not actually an instance.

In fact, the user will likely need to execute that expression within the program and then hoist the result into given/implicit scope, for later sections of the program to use. This is a slightly non-typical way to create instances and I couldn't find any such example in the docs.

• Secondly, the use of the word "instance" here is problematic. It has range of meanings. For people of Haskell persuasion, to call something that's created during the running program for a specific lifetime an "instance" would confuse them.

• And this poses another library design question: why is Random an instance, that is, passed implicitly? Other objects in std like Ref and Queue are passed explicitly, but Random is passed implicitly. Is there a clear principle that specifies why a particular thing is passed explicitly vs implicitly?

Start with the linked std.Random documentation, especially the “Creating a Random instance” section, and try compiling the snippets together. Compare how Random is described with the explicit Ref and Queue APIs; done means the docs include a working creation example and clearly address the terminology and implicit-instance questions.