From f49789e9bdb143c8565cb8a3570b332f34114d08 Mon Sep 17 00:00:00 2001
From: Scot Breitenfeld <brtnfld@hdfgroup.org>
Date: Fri, 22 Nov 2024 15:44:43 -0600
Subject: [PATCH] Clarified the description of the filter ID range.

---
 src/H5Zmodule.h | 26 +-------------------------
 src/H5Zpublic.h | 42 +++++++++++++++++++++++++++++++++++-------
 2 files changed, 36 insertions(+), 32 deletions(-)

diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h
index 8c1dc467042..d8e01676d6f 100644
--- a/src/H5Zmodule.h
+++ b/src/H5Zmodule.h
@@ -96,31 +96,7 @@
  * behavior.  Each filter also has an optional ASCII comment
  * string.
  *
- *     <table>
- *     <tr>
- *       <th>Values for <code>#H5Z_filter_t</code></th><th>Description</th>
- *     </tr>
- *     <tr>
- *       <td><code>0-255</code></td>
- *       <td>These values are reserved for filters predefined and
- *            registered by the HDF5 library and of use to the general
- *            public.</td>
- *     </tr>
- *     <tr>
- *       <td><code>256-511</code></td>
- *       <td>Filter numbers in this range are used for testing only
- *            and can be used temporarily by any organization.  No
- *            attempt is made to resolve numbering conflicts since all
- *            definitions are by nature temporary.</td>
- *     </tr>
- *     <tr>
- *       <td><code>512-65535</code></td>
- *       <td>Reserved for future assignment. Please contact the
- *            <a href="mailto:help@hdfgroup.org">HDF5 development team</a>
- *            to reserve a value or range of values for
- *            use by your filters.</td>
- *    </tr>
- *    </table>
+ * \snippet{doc} H5Zpublic.h FiltersIdTable
  *
  * Filter identifiers for the filters distributed with the HDF5
  * Library are as follows:
diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h
index c3927dc682e..06512f56435 100644
--- a/src/H5Zpublic.h
+++ b/src/H5Zpublic.h
@@ -14,16 +14,44 @@
 #define H5Zpublic_H
 
 #include "H5public.h" /* Generic Functions                        */
-
 /**
  * \brief Filter identifiers
  *
- * \details Values 0 through 255 are for filters defined by the HDF5 library.
- *          Values 256 through 511 are available for testing new filters.
- *          Subsequent values should be obtained from the HDF5 development team
- *          at mailto:help@hdfgroup.org. These values will never change because
- *          they appear in the HDF5 files.
- */
+ * [FiltersIdTable]
+  <table>
+  <tr>
+    <th>Values for <code>#H5Z_filter_t</code></th><th>Description</th>
+  </tr>
+  <tr>
+    <td><code>0-255</code></td>
+    <td>These values are reserved for filters predefined and
+         registered by the HDF5 library and of use to the general public.</td>
+  </tr>
+  <tr>
+    <td><code>256-511</code></td>
+    <td>Filter values in this range are intended for testing only and can be
+        temporarily used by any organization. No attempts are made to resolve
+        numbering conflicts, as all definitions are temporary.</td>
+  </tr>
+  <tr>
+    <td><code>512-32,767</code></td>
+    <td>Filter values within this range are designated for filters managed by
+        The HDF Group, but they are nominally requested, developed, and supported
+        by third parties. Please contact the
+        <a href="mailto:help@hdfgroup.org">HDF5 development team</a>
+        to reserve a value or range of values for use by your filters.</td>
+  </tr>
+  <tr>
+    <td><code>32,768-65,535</code></td>
+    <td>Filter values in this range are designated for internal company use or
+        application testing when assessing a feature. The HDF Group does not
+        track or document the use of filters within this range.
+    </td>
+  </tr>
+  </table>
+  * [FiltersIdTable]
+*/
+
 typedef int H5Z_filter_t;
 
 /* Filter IDs */