[quibble/documentation] is_square for matrices (esp. ZZMatrix)

[JohnAAbbott]

The function is_square can be used to determine if the shape of a matrix is square.
The documentation for is_square does not cover this case, but in every documented version the function tests whether the given argument is the square of some value. There are 5 documented versions: they all say exactly the same, except for one which inserts the (superfluous?) word perfect. There are 52 methods for is_square.

Questions:

1. Can/Should we condense the documentation into a single entry? Maybe a separate entry for matrices?
2. Given that the semantics of is_square for matrices is different, should it have a different name? e.g. is_square_matrix One could also ask whether a given matrix is a square value; not sure this is ever useful, and I don't know how to check it.

I think (1) is a good idea, and am not convinced by the possible merits of (2).

[fingolfin]

Regarding 1: in my opinion yes, and there are many, many other similar examples. In fact I think there is an issue somewhere (probably on AA or Oscar, probably by me) about this matter.

One reason why people might wish to keep separate docstrings is for inserting specific examples; or so they can insert that docstring in their documentation chapter. I can see the merit of the former, but not of the latter: the solution there is IMHO to have a text in the manual for the relevant type which states something like "Besides the general ring interface, this type also provides methods for is_square, factor, and roots."

Regarding 2 resp. the general point: I agree that it is confusing that is_square has these unrelated meanings. However, a matrix is not a ring element and in general matrices can't be squared, unless they are, uhh, square. For MatRingElem (= matrix ring elements), things are different, though.

I think the solution for both 1 and 2 is to have exactly two docstrings for is_square: one for is_square(::NCRingElem), and one for is_square(::MatElem).

(The former one might mention that is_square is not implemented for all ring types)

[fingolfin]

@JohnAAbbott perhaps you'd like to work on this? :-)

[thofma]

There is a (closed?) issue somewhere about (2), where we discussed this. But I can't find it right now. @fingolfin do you remember this discussion?

[fingolfin]

@thofma ahhh indeed: thofma/Hecke.jl#685

[JohnAAbbott]

See PR Nemocas/AbstractAlgebra.jl#2186