Make it clear that `randgen/set-seed` should be used to get a random seed

[bluMyst]

In the documentation for spork/randgen, I think there should be a section at the top that explains that the results of running randgen functions are deterministic by default (they'll be the same every time you run your program) and the way to avoid this is by running something like:

(randgen/set-seed (os/time))

Or some other sane default way to set the random seed.

That way newcomers from languages like Python or JavaScript - where the random seed is set to something unique by default - won't be left wondering why the random number generation in Janet "doesn't work".

It might also be helpful to have some similar notes for the random functions inside of math, but the community examples might be enough in that case.

[sogaiu]

The first suggestion makes sense to me.

I think the source for spork docs actually live at the spork repository though. The current version of the specific file in question here might be this one.

Perhaps an issue and/or PR at the spork repository might be worthwhile [1].

---

About:

It might also be helpful to have some similar notes for the random functions inside of math,

I think this might depend on the specifics as there is some desire to not have the docstrings get too large [2].

but the community examples might be enough in that case.

That sounds fine to me.

An additional option (doesn't preclude the others) is to add examples to janet-lang.org. There is some information on that here along with a summary of some past activities here that spell out some more details.

---

[1] With respect to making it clear that suggestions for spork's documentation be done at spork's repository, this might be worth mentioning in the README for this repository. May be an issue and/or PR for this would make sense. I might work on that if no one else is inclined to do so.

[2] See the question that starts "You've written that you prefer shorter docstrings, ..." at this interview.