Add note to H5Tset_fields about needing to set datatype precision first (#4059)

* Offset of a floating-point type also needs to be accounted for

* Clarify ordering of H5Tset_precision and H5Tset_fields

1 files changed, 11 insertions, 0 deletions

diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index a117075..abf64d9 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -2568,6 +2568,17 @@ H5_DLL herr_t H5Tset_sign(hid_t type_id, H5T_sign_t sign);
  *          Fields are not allowed to extend beyond the number of bits of
  *          precision, nor are they allowed to overlap with one another.
  *
+ * \note The size and precision of, as well as any offset for, a floating-point
+ *       datatype should generally be set appropriately before calling
+ *       H5Tset_fields(). Otherwise, H5Tset_fields() may fail when checking that
+ *       the values make sense for the datatype. However, if the precision of a
+ *       floating-point datatype will be decreased during its creation with a call
+ *       to H5Tset_precision(), then H5Tset_fields() should instead be called
+ *       first to set appropriate values for \p spos, \p epos, \p esize, \p mpos
+ *       and \p msize before reducing the precision of the datatype with
+ *       H5Tset_precision(). This is of particular concern if another floating-point
+ *       datatype was copied as a starting point.
+ *
  * \since 1.0.0
  *
  */