search

gap-system / gap

Main development repository for GAP - Groups, Algorithms, Programming, a System for Computational Discrete Algebra
https://www.gap-system.org
GNU General Public License v2.0
804 stars 163 forks source link

Random source are documented in "Integers" chapter; move them? (to a new chapter)? #1057

Open fingolfin opened 7 years ago

fingolfin commented 7 years ago

Right now, Random source are documented in section 14.17 of the "Integers" chapter. I find that quite counterintuitive and really weird.

So perhaps we should move them to a more appropriate location? Perhaps together with section 30.7 "Random Elements"

But where? Perhaps to a new chapter? But are we willing to insert a new chapter, as that would renumber all following chapters, and break hyperlinks of package manuals... ??

And if we move it to a new chapter, would it be a chapter title "Random", or rather a chapter "Miscellaneous", and we'd move some other things there which are weirdly placed right now (IIRC there are some, but I don't know any from the top of my head).

ChrisJefferson commented 7 years ago

It is weird. I wonder also if we should document every specialisation of Random, or just the general method.

fingolfin commented 7 years ago

@ChrisJefferson See also #116

fingolfin commented 6 years ago

At the very least, it would be good to merge the documentation for Random( listorcoll ) and Random( rs, list ) (into an entry saying Random( [rs, ]listorcoll ), I guess?) and similar for Random( from, to ) and Random( rs, low, high ). Right now, I think neither refers to the other.

Moreover, some of them are defined and documented in coll.gd, the others in random.gd. When merging their documentation, I'd also move their declarations into the same file (preferable random.gd?) and move them together.

And while we are at it, random source arguments should ideally also be added to PseudoRandom and RandomList. Note that the latter is useful as an alternative to Random(list) because it avoids the method selection overhead (which is very heavy for lists, as their types has to be recomputed each time).