Clarify documentation of GeneratorsOfDomain and add an example

[ssiccha]

A domain comes with an associated operational structure. The documentation for GeneratorsOfDomain states:

For a domain D, GeneratorsOfDomain returns a list containing all elements of D,
perhaps with repetitions.

I'm changing this to:

For a domain D, GeneratorsOfDomain returns a list containing generators of D with respect to its operational structure.
The returned list may contain repetitions.

[coveralls]

Coverage increased (+0.0006%) to 85.17% when pulling f14c871 on ssiccha:ss/doc-GeneratorsOfDomain into 87794e8 on gap-system:master.

[fingolfin]

I don't think that's the intended meaning of GeneratorsOfDomain. Think about it: GeneratorsOfGroup returns the generators of an object viewed as a group, i.e., generators relative to the category of groups. For the same object, you can also call GeneratorsOfSemigroup or GeneratorsOfMagma, and they each give you larger sets. My interpretation thus is that GeneratorsOfDomain returns the most general set of generators, namely those relative to the category "Set".

[fingolfin]

Of course we may now argue that this is not what it should be; but then the question is, what should it do? How do we decide which kind of "generators" are supposed to be returned? Those of a magma? A semigroup? A monoid? A group? A ring? A ring-with-one? etc. ... Or perhaps "The most specific one?" -- assuming that is always well-defined?

[ssiccha]

Ah, I've interpreted the following section in the documentation as if there were a unique operational structure attached to a domain.

One important difference between the operational structure and the properties of
a  domain  is  that  the  operational  structure  is  fixed  when  the domain is
constructed,  whereas  properties  can  be discovered later.

But since domains are modelled via filters there can't be a unique "most specific with respect to inclusion" one.

In #3460 I suggest a category IsSetAsDomain. Would it make sense to add a documented synonym for GeneratorsOfDomain by the name of e.g. GeneratorsOfSetAsDomain?

Would it be problematic if installations of GeneratorsOfDomain assume another operational structure than the trivial one? Note that permutation groups don't have any method installed for GeneratorsOfDomain.

[ssiccha]

Note that permutation groups don't have any method installed for GeneratorsOfDomain. That's not true. Actually we have

gap> G := Group([(1,2), (3,4)]);
Group([ (1,2), (3,4) ])
gap> GeneratorsOfDomain(G);
[ (), (3,4), (1,2), (1,2)(3,4) ]

So GeneratorsOfDomain returns generators with respect to the trivial operational structure, that is it returns the domain as a set, as @fingolfin said. I will update my PR to clarify this in the documentation.

[codecov]

Codecov Report

❗ No coverage uploaded for pull request base (master@87794e8). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master    #3453   +/-   ##
=========================================
  Coverage          ?   85.34%           
=========================================
  Files             ?      699           
  Lines             ?   346465           
  Branches          ?        0           
=========================================
  Hits              ?   295675           
  Misses            ?    50790           
  Partials          ?        0

Impacted Files	Coverage Δ
lib/domain.gd	100% <ø> (ø)

[ssiccha]

Nevermind my previous suggestions. I just updated this PR and I think the new version is a lot clearer.