Document global registered filters and codecs

Blosc · Feb 7, 2024 · e0918a1 · e0918a1
1 parent 8c519b4
commit e0918a1
Show file tree

Hide file tree

Showing 5 changed files with 46 additions and 5 deletions.
diff --git a/doc/Doxyfile b/doc/Doxyfile
@@ -7,7 +7,7 @@ GENERATE_RTF         = NO
 CASE_SENSE_NAMES     = NO
 GENERATE_HTML        = NO
 GENERATE_XML         = YES
-RECURSIVE            = NO
+RECURSIVE            = YES
 QUIET                = YES
 JAVADOC_AUTOBRIEF    = YES
 WARN_IF_UNDOCUMENTED = NO

diff --git a/doc/reference/utility_variables.rst b/doc/reference/utility_variables.rst
@@ -33,6 +33,14 @@ Codes for filters
 
 .. doxygenenumvalue:: BLOSC_TRUNC_PREC
 
+.. doxygenenumvalue:: BLOSC_FILTER_NDCELL
+
+.. doxygenenumvalue:: BLOSC_FILTER_NDMEAN
+
+.. doxygenenumvalue:: BLOSC_FILTER_BYTEDELTA
+
+.. doxygenenumvalue:: BLOSC_FILTER_INT_TRUNC
+
 
 Compressor codecs
 -----------------
@@ -46,6 +54,18 @@ Compressor codecs
 
 .. doxygenenumvalue:: BLOSC_ZSTD
 
+.. doxygenenumvalue:: BLOSC_CODEC_NDLZ
+
+.. doxygenenumvalue:: BLOSC_CODEC_ZFP_FIXED_ACCURACY
+
+.. doxygenenumvalue:: BLOSC_CODEC_ZFP_FIXED_PRECISION
+
+.. doxygenenumvalue:: BLOSC_CODEC_ZFP_FIXED_RATE
+
+.. doxygenenumvalue:: BLOSC_CODEC_OPENHTJ2K
+
+.. doxygenenumvalue:: BLOSC_CODEC_GROK
+
 
 Compressor names
 ----------------

diff --git a/include/blosc2.h b/include/blosc2.h
@@ -251,7 +251,7 @@ enum {
   BLOSC_BITSHUFFLE = 2,  //!< Bit-wise shuffle.
 #endif // BLOSC_H
   BLOSC_DELTA = 3,       //!< Delta filter.
-  BLOSC_TRUNC_PREC = 4,  //!< Truncate mantissa precision; positive values in cparams.filters_meta will keep bits; negative values will reduce bits.
+  BLOSC_TRUNC_PREC = 4,  //!< Truncate mantissa precision; positive values in `filters_meta` will keep bits; negative values will zero bits.
   BLOSC_LAST_FILTER = 5, //!< sentinel
   BLOSC_LAST_REGISTERED_FILTER = BLOSC2_GLOBAL_REGISTERED_FILTERS_START + BLOSC2_GLOBAL_REGISTERED_FILTERS - 1,
   //!< Determine the last registered filter. It is used to check if a filter is registered or not.

diff --git a/include/blosc2/codecs-registry.h b/include/blosc2/codecs-registry.h
@@ -19,11 +19,22 @@ extern "C" {
 
 enum {
     BLOSC_CODEC_NDLZ = 32,
+    //!< Simple Lempel-Ziv compressor for NDim data. Experimental, mainly for teaching purposes.
     BLOSC_CODEC_ZFP_FIXED_ACCURACY = 33,
+    //!< ZFP compressor for fixed accuracy mode. The desired accuracy is set in `compcode_meta`.
+    //!< See https://github.com/Blosc/c-blosc2/blob/main/plugins/codecs/zfp/README.md
     BLOSC_CODEC_ZFP_FIXED_PRECISION = 34,
+    //!< ZFP compressor for fixed precision. The desired precision is set in `compcode_meta`.
+    //!< See https://github.com/Blosc/c-blosc2/blob/main/plugins/codecs/zfp/README.md
     BLOSC_CODEC_ZFP_FIXED_RATE = 35,
+    //!< ZFP compressor for fixed precision. The desired rate is set in `compcode_meta`.
+    //!< See https://github.com/Blosc/c-blosc2/blob/main/plugins/codecs/zfp/README.md
     BLOSC_CODEC_OPENHTJ2K = 36,
+    //!< OpenHTJ2K compressor for JPEG 2000 HT.
+    //!< See https://github.com/Blosc/blosc2_openhtj2k
     BLOSC_CODEC_GROK = 37,
+    //!< Grok compressor for JPEG 2000.
+    //!< See https://github.com/Blosc/blosc2_grok
 };
 
 void register_codecs(void);

diff --git a/include/blosc2/filters-registry.h b/include/blosc2/filters-registry.h
@@ -17,10 +17,20 @@ extern "C" {
 
 enum {
     BLOSC_FILTER_NDCELL = 32,
+    //!< Simple filter for grouping NDim cell data together.
+    //!< See https://github.com/Blosc/c-blosc2/blob/main/plugins/filters/ndcell/README.md
     BLOSC_FILTER_NDMEAN = 33,
-    BLOSC_FILTER_BYTEDELTA_BUGGY = 34, // buggy version. See #524
-    BLOSC_FILTER_BYTEDELTA = 35,  // fixed version
-    BLOSC_FILTER_INT_TRUNC = 36,  // truncate int precision; positive values in cparams.filters_meta will keep bits; negative values will reduce bits.
+    //!< Simple filter for replacing content of a NDim cell with its mean value.
+    //!< See https://github.com/Blosc/c-blosc2/blob/main/plugins/filters/ndmean/README.md
+    BLOSC_FILTER_BYTEDELTA_BUGGY = 34,
+    // buggy version. See #524
+    BLOSC_FILTER_BYTEDELTA = 35,
+    //!< Byteshuffle + delta.  Sometimes this can represent an advantage over
+    //!< @ref BLOSC_SHUFFLE or @ref BLOSC_BITSHUFFLE.
+    //!< See https://www.blosc.org/posts/bytedelta-enhance-compression-toolset/
+    BLOSC_FILTER_INT_TRUNC = 36,
+    //!< Truncate int precision; positive values in `filter_meta` will keep bits; negative values will zero bits.
+    //!< This is similar to @ref BLOSC_TRUNC_PREC, but for integers instead of floating point data.
 };
 
 void register_filters(void);