gcdinv documentation is incomplete

[fingolfin]

Consider this excerpt from the FLINT documentation:

.. function:: void fmpz_mod_poly_gcdinv(fmpz_mod_poly_t G, fmpz_mod_poly_t S, const fmpz_mod_poly_t A, const fmpz_mod_poly_t B, const fmpz_mod_ctx_t ctx)

    Computes polynomials `G` and `S`, both reduced modulo~`B`,
    such that `G \cong S A \pmod{B}`, where `B` is assumed to
    have `\operatorname{len}(B) \geq 2`.

    In the case that `A = 0 \pmod{B}`, returns `G = S = 0`.

It does not actually specify G and S in a meaningful way. Note in particular that an implementation which always return G = S = 0 would satisfy this specification.

A similar text with the same problem is used in several other *_gcdinv documentation texts.

Not for fmpz_gcdinv, though:

.. function:: void fmpz_gcdinv(fmpz_t d, fmpz_t a, const fmpz_t f, const fmpz_t g)

    Given integers `f, g` with `0 \leq f < g`, computes the
    greatest common divisor `d = \gcd(f, g)` and the modular
    inverse `a = f^{-1} \pmod{g}`, whenever `f \neq 0`.

This is a bit better, but actually also insufficient: if f, g are not coprime then there is obviously no inverse of f modulo g. So it doesn't say what happens in that case.

(The requirement $0 \leq f < g$ also seems somewhat arbitrary, but OK, you can specify it that way of course).

In AbstractAlgebra we instead switch to the following definition (which does not match what FLINT does), to get a uniform and simple description at the price of potential performance loss in the corner cases (such as $f$ a multiple of $g$) that we normally don't care about, however. It seems to match what fmpz_gcdinv does, too (in the "generic" case at least)

  gcdinv(f::T, g::T) where T <: RingElem

  Return a tuple d, s such that d = gcd(f, g) and s = (f/d)^{-1} \pmod{g/d}. Note that d = 1 iff f is invertible
  modulo g, in which case s = f^{-1} \pmod{g}.

Perhaps some similar verbiage can be adopted in FLINT, too. (And the implementations be modified to match this specification.)

[albinahlback]

Agreed. Could be handled in #2094.