_ptr and _srcptr types

[Emmanuel Thomé]

Hi,

The mpz_ptr, mpz_srcptr types, and their many friends, are exposed in
gmp.h, but never seen in the documentation. (unless I'm mistaken.)

Well, almost:

~/gmp $ grep 'mp[a-z]*_[a-z]*ptr' doc/gmp.texi
@deftypefun mpz_srcptr mpz_roinit_n (mpz_t @var{x}, const mp_limb_t *@var{xp}, mp_size_t @var{xs})

(which leaves the reader a but puzzled, as mpz_srcptr is really unheard
of in the doc).


I've personally always used the mpz_ptr and mpz_srcptr in functions that
take mpz arguments, taking the liberty to use this undocumented type.

I vaguely remember that at some point I had a compelling argument for
doing so, like "it's much better for constness", but I'm not so sure now.
Maybe it's just a matter of taste.

A few random thoughts on this. Admittedly, none qualifies as compelling.
    - sizeof() of mpz_t arguments would be misleading as it's really the
      size of the pointer.
    - the gmp.h prototypes are written with mpz_ptr and mpz_srcptr
      anyway.
    - a custom C++ wrapper type may define an automatic cast to mpz_ptr
      and mpz_srcptr, but certainly not to mpz_t.


May I suggest one or several of the following things be done ?
 - document the mpz_srcptr type somewhere, so that the documentation is
   self-contained.
 - document all the mp*_*ptr types
 - also define and expose gmp_randstate_{src,}ptr, which are currently
   missing.
 - (most probably too extreme): document prototypes as they're actually
   exposed, that is with mpX_ptr arguments rather than mpX_t.

If the first items are agreed upon, the main question would be "where
should the _ptr types be documented ?".  Under "3.5 Parameter
Conventions" maybe ? I might suggest a wording if needed.

Cheers,

E.