documentation issue

[Paul Zimmermann]

>    -- Function: int mpz_invert (mpz_t ROP, mpz_t OP1, mpz_t OP2)
>        Compute the inverse of OP1 modulo OP2 and put the result in ROP.
>        If the inverse exists, the return value is non-zero and ROP will
>        satisfy 0 <= ROP < OP2.  If an inverse doesn't exist the return
>                ^^^^^^^^
>        value is zero and ROP is undefined.
>   
> Is something not working right for |OP2| = 1?  The documentation
> doesn't mention it explicitly, but since its workding is right for
> this case, I don't see any need.  (Just as OP2=4711 does not need
> special wording...)

indeed, the fact that the return value is zero for |OP2|=1 does not agree
with the documentation. Take for example OP1=17 and OP2=1, then ROP=0
satisfies ROP*OP1 = 1 (mod OP2), thus an inverse exists, and according
to the documentation, one should get a non-zero return value, with ROP=0
(this would be the only case where ROP=0).

Conversely, for OP2=0, I don't understand why the return value is non-zero
for OP1=1 or -1, with ROP=1. Most implementations I know of raise a "Division
by zero" error when OP2=0, whatever the value of OP1.

Those two examples show that the documentation should precisely define what
is meant by "inverse of OP1 modulo OP2", especially in those special cases.

Paul