Documentation

[idontgetoutmuch]

I am not sure how much of this is now relevant and how it should be re-written

The library is split into two layers:

A core random number generator provides a supply of bits. The class
RandomGen provides a common interface to such generators. The library
provides one instance of RandomGen, the abstract data type
StdGen. Programmers may, of course, supply their own instances of
RandomGen.

The class Random provides a way to extract values of a particular type
from a random number generator. For example, the Float instance of
Random allows one to generate random values of type Float.

[idontgetoutmuch]

Are we going to document that the old interface still exists but is deprecated and that users should use uniform on a restricted set of types (for efficiency)?

Further if they need uniformly distributed floating point numbers they can use the old interface (but noting the risks) or they can use something like random-fu?

[lehins]

@idontgetoutmuch I still don't think we should deprecate Random fully, see my comment and the full discussion about it. Rust has the exact same concept in a form of "Standard" distribution.

I don't know all the languages out there, but I am sure many of them have a similar concept. Important part is that Random does not conflict with Uniform/UniformRange

[idontgetoutmuch]

I am closing #46 as a lot of it is subsumed in @curiousleo's google doc documentation (which will be turned into a PR). There is some useful stuff in it, notably @Shimuuar's documentation on Uniform and UniformRange, hence this note.

[curiousleo]

Just to keep this thread up to date: the Google Doc is now superseded by #61.

[curiousleo]

#61 has now been merged. I'd like to do a pass over the function and typeclass Haddocks at some point to make everything consistent, but that will have to wait until the code changes settle down a bit.

[Boarders]

The new documentation looks very good. Would it be possible to add eventually add a Tutorial module (like: https://hackage.haskell.org/package/pipes-4.0.0/docs/Pipes-Tutorial.html) which goes over best practices from a naive user's perspective and then maybe also talks about the design from an implementer's perspective and perhaps different performance characteristics (i.e. the fastest way to do X is Y).

[idontgetoutmuch]

@Boarders the intention was there would be sufficient examples and tutorial information in the haddock associated with each module. Are you able to review those and make suggestions? It would be great to have a fresh pair of eyes.

[Boarders]

@idontgetoutmuch : Ok sounds good, I'll try to have a look at it and write down any thoughts.

[Boarders]

I managed to get around to reading through the documentation (sorry for the delay!). In general I would say it is fantastic and on top of an order of magnitude improvement in API and performance this also offers an order of magnitude improvement in documentation from the old random. It offers the minimal examples that newcomers or those that just want to get on with another task need to get going (which notably the old random does not!) and the appendices offers plenty for library authors wishing to know how to adapt their PRNG to this interface. Keeping the relevant insights from the discussion regarding floating point generation is also a very nice feature.

One area where I think more documentation (though I am unsure of the best thing to say) might be helpful is in regards to the Frozen type family. There is still ongoing discussion regarding what the final API will look like here but whatever is decided it would be useful to say something like: "Frozen is an immutable type family for storing mutable state, e.g. type Frozen (IOGenM g) = IOGen g." My first read through I did not see the point of the various newtypes: IOGen, STGen, AtomicGen but reading this would have cleared it up (possibly I am just being dense).

[curiousleo]

I managed to get around to reading through the documentation (sorry for the delay!). In general I would say it is fantastic and on top of an order of magnitude improvement in API and performance this also offers an order of magnitude improvement in documentation from the old random. It offers the minimal examples that newcomers or those that just want to get on with another task need to get going (which notably the old random does not!) and the appendices offers plenty for library authors wishing to know how to adapt their PRNG to this interface. Keeping the relevant insights fromt he discussion regarding floating point generation is also a very nice feature.

Thank you very much for taking the time to review the docs, your comments are very much appreciated.

One area where I think more documentation (though I am unsure of the best thing to say) might be helpful is in regards to the Frozen type family. There is still ongoing discussion regarding what the final API will look like here but whatever is decided it would be useful to say something like: "Frozen is an immutable type family for storing mutable state, e.g. type Frozen (IOGenM g) = IOGen g." My first read through I did not see the point of the various newtypes: IOGen, STGen, AtomicGen but reading this would have cleared it up (possibly I am just being dense).

Yep, I think that's on point - there is no high level "intuitive" explanation of what Frozen and its associated type instances are there for. I've filed #146 for this.