document ubuf union in developer guide

doc/src/pg_dev_utils.rst

@@ -171,6 +171,27 @@ Customized standard functions
 
 ---------------------------
 
+Communication buffer coding with *ubuf*
+=========================================
+
+LAMMPS uses communication buffers where it collects data from various
+class instances and then exchanges the data with neighboring subdomains.
+For simplicity those buffers are defined as ``double`` buffers and
+used for doubles and integer numbers. This presents a unique problem
+when 64-bit integers are used.  While the storage needed for a ``double``
+is also 64-bit, it cannot be used by a simple assignment.  To get around
+that limitation, LAMMPS uses the :cpp:union:`ubuf <LAMMPS_NS::ubuf>`
+union.  It is used in the various "pack" and "unpack" functions in the
+LAMMPS classes to store and retrieve integers that may be 64-bit from
+the communication buffers.
+
+---------------------------
+
+.. doxygenunion:: LAMMPS_NS::ubuf
+   :project: progguide
+
+---------------------------
+
 Tokenizer classes
 =================
 

src/lmptype.h

@@ -79,6 +79,7 @@ namespace LAMMPS_NS {
 
 // for atomic problems that exceed 2 billion (2^31) atoms
 // 32-bit smallint/imageint/tagint, 64-bit bigint
+// atom IDs and molecule IDs are limited to 32-bit
 
 #ifdef LAMMPS_SMALLBIG
 
@@ -171,22 +172,21 @@ typedef int bigint;
 
 #endif
 
-  /// Data structe for packing 32-bit and 64-bit integers
+/** Data structure for packing 32-bit and 64-bit integers
-  /// into double (communication) buffers
+ * into double (communication) buffers
-  ///
+ *
-  /// Using this union avoids aliasing issues by having member types
+ * Using this union avoids aliasing issues by having member types
-  /// (double, int) referencing the same buffer memory location.
+ * (double, int) referencing the same buffer memory location.
-  ///
+ *
-  /// The explicit constructor for 32-bit integers prevents compilers
+ * The explicit constructor for 32-bit integers prevents compilers
-  /// from (incorrectly) calling the double constructor when storing
+ * from (incorrectly) calling the double constructor when storing
-  ///  an int into a double buffer.
+ * an int into a double buffer.
-  /*
 \verbatim embed:rst
+
 **Usage:**
 
-To copy an integer into a double buffer:
+.. code-block:: c++
-
+   :caption: To copy an integer into a double buffer:
-.. code-block: c++
 
    double buf[2];
    int    foo =   1;
@@ -194,14 +194,13 @@ To copy an integer into a double buffer:
    buf[1] = ubuf(foo).d;
    buf[2] = ubuf(bar).d;
 
-To copy from a double buffer back to an int:
+.. code-block:: c++
-
+   :caption: To copy from a double buffer back to an int:
-.. code-block: c++
 
    foo = (int)    ubuf(buf[1]).i;
    bar = (tagint) ubuf(buf[2]).i;
 
-The typecast prevents compiler warnings about possible truncations.
+The typecasts prevent compiler warnings about possible truncations.
 \endverbatim
   */
   union ubuf {