From 46e15289fb1c833b687eb473a18a66c5718f6c6e Mon Sep 17 00:00:00 2001
From: Fredrik Johansson <fredrik.johansson@gmail.com>
Date: Wed, 30 Jul 2014 16:58:38 +0200
Subject: [PATCH] document shallow assign functions

---
 arf.h              |  3 ---
 doc/source/arf.rst | 26 +++++++++++++++++++++-----
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/arf.h b/arf.h
index 0b13e4b2..b2de84d4 100644
--- a/arf.h
+++ b/arf.h
@@ -479,14 +479,12 @@ arf_cmpabs_ui(const arf_t x, ulong y)
     return arf_cmpabs(x, t);
 }
 
-/* TODO: document */
 static __inline__ void
 arf_init_set_shallow(arf_t z, const arf_t x)
 {
     *z = *x;
 }
 
-/* TODO: document */
 static __inline__ void
 arf_init_neg_shallow(arf_t z, const arf_t x)
 {
@@ -503,7 +501,6 @@ arf_init_set_mag_shallow(arf_t y, const mag_t x)
     ARF_NOPTR_D(y)[0] = t << (FLINT_BITS - MAG_BITS);
 }
 
-/* TODO: document */
 static __inline__ void
 arf_init_neg_mag_shallow(arf_t z, const mag_t x)
 {
diff --git a/doc/source/arf.rst b/doc/source/arf.rst
index 94e10c9b..0eb5f7a4 100644
--- a/doc/source/arf.rst
+++ b/doc/source/arf.rst
@@ -331,11 +331,6 @@ Magnitude functions
     Initializes *y* and sets it to an upper bound for *x*.
     Assumes that the exponent of *y* is small.
 
-.. function:: void arf_init_set_mag_shallow(arf_t y, const mag_t x)
-
-    Initializes *y* to a shallow copy of *x*. The variable *y* may
-    not be cleared, and may not be used after *x* has been cleared.
-
 .. function:: void arf_mag_set_ulp(mag_t z, const arf_t y, long prec)
 
     Sets *z* to the magnitude of the unit in the last place (ulp) of *y*
@@ -353,6 +348,27 @@ Magnitude functions
     magnitude of the unit in the last place (ulp) of *y*
     at precision *prec*. Assumes that all exponents are small.
 
+Shallow assignment
+-------------------------------------------------------------------------------
+
+.. function:: void arf_init_set_shallow(arf_t z, const arf_t x)
+
+.. function:: void arf_init_set_mag_shallow(arf_t z, const mag_t x)
+
+    Initializes *z* to a shallow copy of *x*. A shallow copy just involves
+    copying struct data (no heap allocation is performed).
+
+    The target variable *z* may not be cleared or modified in any way (it can
+    only be used as constant input to functions), and may not be used after
+    *x* has been cleared. Moreover, after *x* has been assigned shallowly
+    to *z*, no modification of *x* is permitted as long as *z* is in use.
+
+.. function:: void arf_init_neg_shallow(arf_t z, const arf_t x)
+
+.. function:: void arf_init_neg_mag_shallow(arf_t z, const mag_t x)
+
+    Initializes *z* shallowly to the negation of *x*.
+
 Random number generation
 -------------------------------------------------------------------------------