[with patch; positive review] Docstrings and doctests for rings/ring.pyx

[cswiercz]

Provide missing doctests for the file rings/ring.pyx on all non-underscore functions. These include

random_element krull_dimension ideal_monoid quotient_ring is_integral_domain is_integrally_closed is_field is_noetherian

krull_dimension is_integrally_closed integral_closure is_noetherian gcd parameter category fraction_field modulus characteristic is_commutative

[cswiercz]

Missing doctests for most of the non underscore functions in rings/ring.pyx (Need to finish.)

[cswiercz]

Additional doctest for rings/ring.pyx. There are still some doctests leftover for some non-underscore functions. I don't know enough about them to make a decent doctest.

[cremona]

Review:

1. I like all the tests and docs you have added, with one possible exception. Your comment concerning the gcd functions talks about gcds in QQ, saying that they exist since QQ is trivially a PID. There is some confusion here. If you treat QQ as a ring, then gcd(a,b) should be 1 for all a,b in QQ (except a=b=0) since the ideal they generate is the unit ideal. But this is not what gcd(a,b) actually does for a,b in QQ: it returns a generator for the Z-module generated by a and b (rather than the Q-module).

I suspect that this needs better documentation. As it stands, it is certainly confusing.

2. I'll have a go at doctesting the remaining functions.

[cswiercz]

Clarification of QQ.gcd in rings/ring.pyx. Also includes doctests for several basic functions in rings/integer_ring.pyx.

[cremona]

The extra patches and clarifications look good, with one very small exception: ZZ.gens() returns a tuple of length 1, not 2!

sage: ZZ.gens()
(1,)
sage: len(ZZ.gens())
1

It's just that Python displays 1-tuples with a trailing comma.

[cremona]

to be applied after thre previous 3 patches

[cremona]

The attached patch 8812.patch (which need to be applied after the other 3) completes the job of doctesting rings/arith.py, rings/ring.pyx and rings/integer_ring.pyx, as well as correcting the minor glitch in the previous patches,

These passed --testall on 2.10.3.rc2

[cswiercz]

Reviewed the attached patch 8812.patch with positive review. The patches are to be applied in the following order: ring.patch, ring.additional.patch, ring_integer_ring.patch, 8812.patch.

[mabshoff]

Merged all four patches in Sage 2.10.3.rc4