Clean up Doxygen for szip functions and constants (#3943)

2 files changed, 46 insertions, 14 deletions

diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index c6a780f..df0ede1 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -6857,7 +6857,7 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type,
  *                         Valid values are #H5_SZIP_EC_OPTION_MASK and
  *                         #H5_SZIP_NN_OPTION_MASK.
  * \param[in] pixels_per_block The number of pixels or data elements in each
- *            data block
+ *            data block (max #H5_SZIP_MAX_PIXELS_PER_BLOCK)
  *
  * \return \herr_t
  *
@@ -6892,7 +6892,7 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type,
  *          <table>
  *            <tr>
  *             <th>Option</th>
- *             <th>Description (Mutually exclusive; select one.)</th>
+ *             <th>Description (Mutually exclusive; select one)</th>
  *            </tr>
  *            <tr>
  *             <td>#H5_SZIP_EC_OPTION_MASK</td>
@@ -6900,7 +6900,7 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type,
  *            </tr>
  *            <tr>
  *             <td>#H5_SZIP_NN_OPTION_MASK</td>
- *             <td>Selects nearest neighbor coding method</td>
+ *             <td>Selects nearest neighbor preprocessing followed by entropy coding</td>
  *            </tr>
  *           </table>
  *
@@ -6948,9 +6948,10 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type,
  *             conflict can be detected only when the property list is used.
  *           - Users should be aware that there are factors that affect one's
  *             rights and ability to use SZIP compression by reviewing the
- *             SZIP copyright notice.
+ *             SZIP copyright notice. (This limitation does not apply to the
+ *             libaec library).
  *
- * \note \b For \b Users \b Familiar \b with \b SZIP \b in \b Other \b Contexts:
+ * \note <b> For Users Familiar with SZIP in Other Contexts: </b>
  *
  * \note  The following notes are of interest primarily to those who have
  *        used SZIP compression outside of the HDF5 context.
diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h
index 44d91c0..bd557fc 100644
--- a/src/H5Zpublic.h
+++ b/src/H5Zpublic.h
@@ -110,24 +110,55 @@ typedef int H5Z_filter_t;
  */
 #define H5Z_FLAG_SKIP_EDC 0x0200
 
-/* Special parameters for szip compression */
-/* [These are aliases for the similar definitions in szlib.h, which we can't
- * include directly due to the duplication of various symbols with the zlib.h
- * header file] */
+/* Special parameters for szip compression
+ *
+ * These are aliases for similarly-named definitions in szlib.h, which we
+ * can't include directly due to the duplication of various symbols with the
+ * zlib.h header file.
+ *
+ * The flag values are set to the same values as in szlib.h. The following
+ * symbols are internal and defined in H5Zprivate.h:
+ *
+ * - H5_SZIP_LSB_OPTION_MASK
+ * - H5_SZIP_MSB_OPTION_MASK
+ * - H5_SZIP_RAW_OPTION_MASK
+ *
+ * TODO: These symbols should probably be deprecated and moved to H5Zprivate.h
+ *       in the next major release of the library since they are only used
+ *       internally:
+ *
+ * - H5_SZIP_ALLOW_K13_OPTION_MASK
+ * - H5_SZIP_CHIP_OPTION_MASK
+ */
 /**
- * \ingroup SZIP */
+ * \ingroup SZIP
+ *
+ * Used internally. Always added to the \p options_mask parameter of H5Pset_szip().
+ */
 #define H5_SZIP_ALLOW_K13_OPTION_MASK 1
 /**
- * \ingroup SZIP */
+ * \ingroup SZIP
+ *
+ * Used internally. Always removed from the \p options_mask parameter of H5Pset_szip().
+ */
 #define H5_SZIP_CHIP_OPTION_MASK 2
 /**
- * \ingroup SZIP */
+ * \ingroup SZIP
+ *
+ * Use the entropy coding method
+ */
 #define H5_SZIP_EC_OPTION_MASK 4
 /**
- * \ingroup SZIP */
+ * \ingroup SZIP
+ *
+ * Use nearest neighbor preprocessing and then the entropy coding method
+ */
 #define H5_SZIP_NN_OPTION_MASK 32
 /**
- * \ingroup SZIP */
+ * \ingroup SZIP
+ *
+ * The maximum number of pixels per block (see H5Pset_szip())
+ */
 #define H5_SZIP_MAX_PIXELS_PER_BLOCK 32
 
 /* Macros for the shuffle filter */