Combinator naming principles

[jmid]

Before setting out on "The Great Combinator Renaming" ™️ we should document the naming principles.

Here's a cleaned up version distilled from past lessons in #223 and #243:

• Generator names should align with type names (bool, char, ... list, option) - to be as predictable as possible
• We should have short, unparameterized generators (int, string, ...) to lower the barrier to entry
• Specialized generators also start with the type name, but use a consistent suffix (_pos, _neg, _size, _of, ...) as this will help find them, also when using tab-completion
• We may include a few shorthand names for convenience (int_pos->nat, option->opt, ...)
• Overall we aim to be as consistent as possible, e.g., offering similar signatures across generator interfaces (QCheck.Gen, QCheck.arbitrary, QCheck2.Gen)

We've already used these principles, e.g., in naming the bytes and string combinators in #245 as well as in #307 and #308,
so they should not come as a surprise.

Finally: I plan to add these naming principles to the documentation.

[jmid]

I've just opened #367 to address float names.

[jmid]

FTR, the unit and bool situation is consistent (it is admittedly also rather simple):

Combinator name	QCheck.Gen	QCheck.arbitrary	QCheck2.Gen
unit	unit t	unit arbitrary	unit t
bool	bool t	bool arbitrary	bool t

[jmid]

I've now opened #369 to address char names.

[jmid]

I've opened #370 to address option consistency.

For the result type the situation is nice, simple, and already consistent: 🥳

Combinator name	Type signiture
QCheck.Gen.result	?ratio:float -> 'a t -> 'e t -> ('a, 'e) result t
QCheck.result	?ratio:float -> 'a arbitrary -> 'e arbitrary -> ('a, 'e) result arbitrary
QCheck2.Gen.result	?ratio:float -> 'a t -> 'e t -> ('a, 'e) result t

[jmid]

#371 took care of bytes renaming

[jmid]

I've just opened #372 to address string renaming

[jmid]

For int32 and int64 the situation is as follows:

Combinator name	QCheck.Gen	QCheck.arbitrary	QCheck2.Gen
int32	int32 t	int32 arbitrary	int32 t
ui32	int32 t	-	int32 t
int64	int64 t	int64 arbitrary	int64 t
ui64	int64 t	-	int64 t

As such their situation is reasonably consistent.

Furthermore

• QCheck.Gen.ui32
• QCheck2.Gen.ui32
• QCheck.Gen.ui64 and
• QCheck2.Gen.ui64

are already deprecated since 0.24 - and should be removed in our 1.0 release.