Merge pull request #19281 from lydia-duncan/mpzStruct

Adjustments to the visibility of bigint's implementation details
[reviewed by @bmcdonald3]

Stops documenting the `mpz` field for the `bigint` type in the BigInteger
module, and deprecates the `mpzStruct` method in favor of a new method
called `getImpl`, which is documented as an implementation detail that may
change in the future.

Resolves #17694

Updates some uses of the now deprecated method to use the new method
instead.  Updates some documentation links to the `mpz` field to not be
links any more - the field still exists, so it's okay for users to refer to it though
it may become private later when private fields are implemented.

Adds a new test locking in the deprecation message for `mpzStruct`.

Passed a full paratest with futures

modules/standard/BigInteger.chpl

@@ -204,7 +204,8 @@ module BigInteger {
 
   pragma "ignore noinit"
   record bigint {
-    /* The underlying GMP C structure */
+    // The underlying GMP C structure
+    pragma "no doc"
     var mpz      : mpz_t;              // A dynamic-vector of C integers
 
     pragma "no doc"
@@ -222,7 +223,7 @@ module BigInteger {
       if _local || num.localeId == chpl_nodeID {
         mpz_init_set(this.mpz, num.mpz);
       } else {
-        var mpz_struct = num.mpzStruct();
+        var mpz_struct = num.getImpl();
 
         mpz_init(this.mpz);
 
@@ -369,12 +370,12 @@ module BigInteger {
       return ret.safeCast(int);
     }
 
-    deprecated "This method is deprecated, please use :proc:`GMP.chpl_gmp_mpz_nlimbs` on the :var:`mpz` field instead"
+    deprecated "This method is deprecated, please use :proc:`GMP.chpl_gmp_mpz_nlimbs` on the mpz field instead"
     proc numLimbs : uint {
       return chpl_gmp_mpz_nlimbs(this.mpz);
     }
 
-    deprecated "This method is deprecated, please use :proc:`GMP.chpl_gmp_mpz_getlimbn` on the :var:`mpz` field instead"
+    deprecated "This method is deprecated, please use :proc:`GMP.chpl_gmp_mpz_getlimbn` on the mpz field instead"
     proc get_limbn(n: integral) : uint {
       var   ret: uint;
 
@@ -395,7 +396,18 @@ module BigInteger {
       return ret;
     }
 
+    deprecated "mpzStruct is deprecated, please use :proc:`getImpl` instead"
     proc mpzStruct() : __mpz_struct {
+      return getImpl();
+    }
+
+    /* Return the underlying implementation of :record:`bigint`.  Currently,
+       the type returned is ``__mpz_struct``.
+
+       This method is provided as a convenience but its result may change in the
+       future.
+    */
+    proc getImpl(): __mpz_struct {
       var ret: __mpz_struct;
 
       if _local {
@@ -5287,7 +5299,7 @@ module BigInteger {
       const thisLoc = chpl_buildLocaleID(this.localeId, c_sublocid_any);
 
       on __primitive("chpl_on_locale_num", thisLoc) {
-        const mpz_struct = a.mpzStruct();
+        const mpz_struct = a.getImpl();
 
         chpl_gmp_get_mpz(this.mpz, a.localeId, mpz_struct);
       }

test/deprecated/BigInteger/deprecateMpzStruct.chpl

@@ -0,0 +1,9 @@
+use BigInteger;
+use GMP;
+
+config const debug = false;
+
+var a: bigint = 14;
+var impl = a.mpzStruct();
+var ret = chpl_gmp_mpz_nlimbs((impl,));
+if debug then writeln(ret);

test/deprecated/BigInteger/deprecateMpzStruct.good

@@ -0,0 +1 @@
+deprecateMpzStruct.chpl:7: warning: mpzStruct is deprecated, please use getImpl instead