From b5c98fbfd000f21f55ba7c6f60fcd2c0d6ee7852 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Tue, 4 Jun 2019 10:26:16 -0700 Subject: [PATCH 1/2] Added comments on I/O buffer sizes for streaming It seems this is still a confusing topic, as in https://github.com/klauspost/compress/issues/109 . --- doc/zstd_manual.html | 9 +++++---- lib/zstd.h | 24 ++++++++++++++++++++---- 2 files changed, 25 insertions(+), 8 deletions(-) diff --git a/doc/zstd_manual.html b/doc/zstd_manual.html index 1e05f0cb3..bad5f7b97 100644 --- a/doc/zstd_manual.html +++ b/doc/zstd_manual.html @@ -18,7 +18,7 @@
  • Advanced decompression API
  • Streaming
  • Streaming compression - HowTo
    • -
  • This is a legacy streaming API, and can be replaced by ZSTD_CCtx_reset() and
    • +
  • This following is a legacy streaming API.
  • Equivalent to:
  • Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
  • Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush).
    • @@ -592,9 +592,10 @@ size_t ZSTD_freeCStream(ZSTD_CStream* zcs); 
    size_t ZSTD_CStreamInSize(void);    /**< recommended size for input buffer */

    -
    size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block in all circumstances. */
+
    size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block. */
 

    
-
    This is a legacy streaming API, and can be replaced by ZSTD_CCtx_reset() and
     ZSTD_compressStream2(). It is redundant, but is still fully supported.
+
    This following is a legacy streaming API.
     It can be replaced by ZSTD_CCtx_reset() and ZSTD_compressStream2().
+ It is redundant, but remains fully supported.
  Advanced parameters and dictionary compression can only be used through the
  new API.
 
    
@@ -608,7 +609,7 @@ size_t ZSTD_freeCStream(ZSTD_CStream* zcs);
 
 
    Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
     NOTE: The return value is different. ZSTD_compressStream() returns a hint for
  the next read size (if non-zero and not an error). ZSTD_compressStream2()
- returns the number of bytes left to flush (if non-zero and not an error).
+ returns the minimum nb of bytes left to flush (if non-zero and not an error).
  
 
    
 
diff --git a/lib/zstd.h b/lib/zstd.h
index 53470c18f..3ede0441a 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -657,12 +657,28 @@ ZSTDLIB_API size_t ZSTD_compressStream2( ZSTD_CCtx* cctx,
                                          ZSTD_inBuffer* input,
                                          ZSTD_EndDirective endOp);
 
+
+/* These buffer sizes are softly recommended.
+ * They are not required : ZSTD_compressStream*() happily accepts any buffer size, for both input and output.
+ * Respecting the recommended size just makes it a bit easier for ZSTD_compressStream*(),
+ * reducing the amount of memory shuffling and buffering, resulting in minor performance savings.
+ *
+ * However, note that these recommendations are from the perspective of a C caller program.
+ * If the streaming interface is invoked from some other language,
+ * especially managed ones such as Java or Go, through a foreign function interface such as jni or cgo,
+ * a major performance rule is to reduce crossing such interface to an absolute minimum.
+ * It's not rare that performance ends being spent more into the interface, rather than compression itself.
+ * In which cases, prefer using large buffers, as large as practical,
+ * for both input and output, to reduce the nb of roundtrips.
+ */
 ZSTDLIB_API size_t ZSTD_CStreamInSize(void);    /**< recommended size for input buffer */
-ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block in all circumstances. */
+ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block. */
+
 
 /*******************************************************************************
- * This is a legacy streaming API, and can be replaced by ZSTD_CCtx_reset() and
- * ZSTD_compressStream2(). It is redundant, but is still fully supported.
+ * This following is a legacy streaming API.
+ * It can be replaced by ZSTD_CCtx_reset() and ZSTD_compressStream2().
+ * It is redundant, but remains fully supported.
  * Advanced parameters and dictionary compression can only be used through the
  * new API.
  ******************************************************************************/
@@ -679,7 +695,7 @@ ZSTDLIB_API size_t ZSTD_initCStream(ZSTD_CStream* zcs, int compressionLevel);
  * Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
  * NOTE: The return value is different. ZSTD_compressStream() returns a hint for
  * the next read size (if non-zero and not an error). ZSTD_compressStream2()
- * returns the number of bytes left to flush (if non-zero and not an error).
+ * returns the minimum nb of bytes left to flush (if non-zero and not an error).
  */
 ZSTDLIB_API size_t ZSTD_compressStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
 /** Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush). */

From b3af1873a0b50c1d3545da53786b15f998dd54f7 Mon Sep 17 00:00:00 2001
From: Yann Collet 
Date: Tue, 4 Jun 2019 10:35:40 -0700
Subject: [PATCH 2/2] better title formatting for html documentation

must pay attention to /** and /*! patterns.
---
 doc/zstd_manual.html | 159 ++++++++++++++++++-------------------------
 lib/zstd.h           |  28 ++++----
 2 files changed, 80 insertions(+), 107 deletions(-)

diff --git a/doc/zstd_manual.html b/doc/zstd_manual.html
index bad5f7b97..024c10e63 100644
--- a/doc/zstd_manual.html
+++ b/doc/zstd_manual.html
@@ -10,37 +10,27 @@
 
      
 
    1. Introduction
      2. 
 
    2. Version
      3. 
-
    3. Default constant
      4. 
-
    4. Constants
      5. 
-
    5. Simple API
      6. 
-
    6. Explicit context
      7. 
-
    7. Advanced compression API
      8. 
-
    8. Advanced decompression API
      9. 
-
    9. Streaming
      10. 
-
    10. Streaming compression - HowTo
      11. 
-
    11. This following is a legacy streaming API.
      12. 
-
    12. Equivalent to:
      13. 
-
    13. Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
      14. 
-
    14. Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush).
      15. 
-
    15. Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_end).
      16. 
-
    16. Streaming decompression - HowTo
      17. 
-
    17. Simple dictionary API
      18. 
-
    18. Bulk processing dictionary API
      19. 
-
    19. Dictionary helper functions
      20. 
-
    20. Advanced dictionary and prefix API
      21. 
-
    21. ADVANCED AND EXPERIMENTAL FUNCTIONS
      22. 
-
    22. experimental API (static linking only)
      23. 
-
    23. Frame size functions
      24. 
-
    24. ZSTD_decompressBound() :
      25. 
-
    25. Memory management
      26. 
-
    26. Advanced compression functions
      27. 
-
    27. Advanced decompression functions
      28. 
-
    28. Advanced streaming functions
      29. 
-
    29. Buffer-less and synchronous inner streaming functions
      30. 
-
    30. Buffer-less streaming compression (synchronous mode)
      31. 
-
    31. Buffer-less streaming decompression (synchronous mode)
      32. 
-
    32. ZSTD_getFrameHeader() :
      33. 
-
    33. Block level API
      34. 
+
    34. Simple API
      35. 
+
    35. Explicit context
      36. 
+
    36. Advanced compression API
      37. 
+
    37. Advanced decompression API
      38. 
+
    38. Streaming
      39. 
+
    39. Streaming compression - HowTo
      40. 
+
    40. Streaming decompression - HowTo
      41. 
+
    41. Simple dictionary API
      42. 
+
    42. Bulk processing dictionary API
      43. 
+
    43. Dictionary helper functions
      44. 
+
    44. Advanced dictionary and prefix API
      45. 
+
    45. experimental API (static linking only)
      46. 
+
    46. Frame size functions
      47. 
+
    47. Memory management
      48. 
+
    48. Advanced compression functions
      49. 
+
    49. Advanced decompression functions
      50. 
+
    50. Advanced streaming functions
      51. 
+
    51. Buffer-less and synchronous inner streaming functions
      52. 
+
    52. Buffer-less streaming compression (synchronous mode)
      53. 
+
    53. Buffer-less streaming decompression (synchronous mode)
      54. 
+
    54. Block level API
      55. 
 
    
 
    
 
    Introduction
    @@ -78,11 +68,7 @@
 
 
    unsigned ZSTD_versionNumber(void);   /**< to check runtime library version */
 

    
-
    Default constant
    
-
-
    Constants
    
-
-
    Simple API
    
+
    Simple API
    
 
 
    size_t ZSTD_compress( void* dst, size_t dstCapacity,
                 const void* src, size_t srcSize,
@@ -152,7 +138,7 @@ const char* ZSTD_getErrorName(size_t code);     /*!< provides readable strin
 int         ZSTD_minCLevel(void);               /*!< minimum negative compression level allowed */
 int         ZSTD_maxCLevel(void);               /*!< maximum compression level available */
 

    
-
    Explicit context
    
+
    Explicit context
    
 
 
    Compression context
      When compressing many times,
   it is recommended to allocate a context just once, and re-use it for each successive compression operation.
@@ -189,7 +175,7 @@ size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);
  
 

    
 
-
    Advanced compression API
    
+
    Advanced compression API
    
 
 
    typedef enum { ZSTD_fast=1,
                ZSTD_dfast=2,
@@ -424,7 +410,7 @@ size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);
  
 

    
 
-
    Advanced decompression API
    
+
    Advanced decompression API
    
 
 
    typedef enum {
 
@@ -472,7 +458,7 @@ size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);
  
 

    
 
-
    Streaming
    
+
    Streaming
    
 
 
    typedef struct ZSTD_inBuffer_s {
   const void* src;    /**< start of input buffer */
@@ -486,7 +472,7 @@ size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);
   size_t pos;         /**< position where writing stopped. Will be updated. Necessarily 0 <= pos <= size */
 } ZSTD_outBuffer;
 

    
-
    Streaming compression - HowTo
    +
    Streaming compression - HowTo
       A ZSTD_CStream object is required to track streaming operation.
   Use ZSTD_createCStream() and ZSTD_freeCStream() to create/release resources.
   ZSTD_CStream objects can be reused multiple times on consecutive compression operations.
@@ -594,30 +580,26 @@ size_t ZSTD_freeCStream(ZSTD_CStream* zcs);
 

    
 
    size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block. */
 

    
-
    This following is a legacy streaming API.
     It can be replaced by ZSTD_CCtx_reset() and ZSTD_compressStream2().
- It is redundant, but remains fully supported.
- Advanced parameters and dictionary compression can only be used through the
- new API.
-
    
-
-
    Equivalent to:
    +
    size_t ZSTD_initCStream(ZSTD_CStream* zcs, int compressionLevel);
+/*!
+ * Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
+ * NOTE: The return value is different. ZSTD_compressStream() returns a hint for
+ * the next read size (if non-zero and not an error). ZSTD_compressStream2()
+ * returns the minimum nb of bytes left to flush (if non-zero and not an error).
+ */
+size_t ZSTD_compressStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
+/*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush). */
+size_t ZSTD_flushStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
+/*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_end). */
+size_t ZSTD_endStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
+
    
      ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
      ZSTD_CCtx_refCDict(zcs, NULL); // clear the dictionary (if any)
      ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
  
-
    
+

    
 
-
    Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
     NOTE: The return value is different. ZSTD_compressStream() returns a hint for
- the next read size (if non-zero and not an error). ZSTD_compressStream2()
- returns the minimum nb of bytes left to flush (if non-zero and not an error).
- 
-
    
-
-
    Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush).
    
-
-
    Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_end).
    
-
-
    Streaming decompression - HowTo
    +
    Streaming decompression - HowTo
       A ZSTD_DStream object is required to track streaming operations.
   Use ZSTD_createDStream() and ZSTD_freeDStream() to create/release resources.
   ZSTD_DStream objects can be re-used multiple times.
@@ -653,7 +635,7 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds);
 

    
 
    size_t ZSTD_DStreamOutSize(void);   /*!< recommended size for output buffer. Guarantee to successfully flush at least one complete block in all circumstances. */
 

    
-
    Simple dictionary API
    
+
    Simple dictionary API
    
 
 
    size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,
                                void* dst, size_t dstCapacity,
@@ -679,7 +661,7 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds);
   Note : When `dict == NULL || dictSize < 8` no dictionary is used. 
 

    
 
-
    Bulk processing dictionary API
    
+
    Bulk processing dictionary API
    
 
 
    ZSTD_CDict* ZSTD_createCDict(const void* dictBuffer, size_t dictSize,
                              int compressionLevel);
@@ -722,7 +704,7 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds);
   Recommended when same dictionary is used multiple times. 
 

    
 
-
    Dictionary helper functions
    
+
    Dictionary helper functions
    
 
 
    unsigned ZSTD_getDictID_fromDict(const void* dict, size_t dictSize);
 
      Provides the dictID stored within dictionary.
@@ -748,7 +730,7 @@ size_t ZSTD_freeDStream(ZSTD_DStream* zds);
   When identifying the exact failure cause, it's possible to use ZSTD_getFrameHeader(), which will provide a more precise error code. 
 

    
 
-
    Advanced dictionary and prefix API
    +
    Advanced dictionary and prefix API
      This API allows dictionaries to be used with ZSTD_compress2(),
  ZSTD_compressStream2(), and ZSTD_decompress(). Dictionaries are sticky, and
  only reset with the context is reset with ZSTD_reset_parameters or
@@ -866,15 +848,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
   Note that object memory usage can evolve (increase or decrease) over time. 
 

    
 
-
    ADVANCED AND EXPERIMENTAL FUNCTIONS
    - The definitions in the following section are considered experimental.
- They are provided for advanced scenarios.
- They should never be used with a dynamic library, as prototypes may change in the future.
- Use them only in association with static linking.
- 
-
    
-
-
    experimental API (static linking only)
    +
    experimental API (static linking only)
      The following symbols and constants
  are not planned to join "stable API" status in the near future.
  They can still change in future versions.
@@ -972,7 +946,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
   ZSTD_lcm_uncompressed = 2,  /**< Always emit uncompressed literals. */
 } ZSTD_literalCompressionMode_e;
 

    
-
    Frame size functions
    
+
    Frame size functions
    
 
 
    unsigned long long ZSTD_findDecompressedSize(const void* src, size_t srcSize);
 
      `src` should point to the start of a series of ZSTD encoded and/or skippable frames
@@ -997,7 +971,8 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
             however it does mean that all frame data must be present and valid. 
 

    
 
-
    ZSTD_decompressBound() :
      `src` should point to the start of a series of ZSTD encoded and/or skippable frames
+
    unsigned long long ZSTD_decompressBound(const void* src, size_t srcSize);
+
      `src` should point to the start of a series of ZSTD encoded and/or skippable frames
   `srcSize` must be the _exact_ size of this series
        (i.e. there should be a frame boundary at `src + srcSize`)
   @return : - upper-bound for the decompressed size of all data in all successive frames
@@ -1009,7 +984,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
   note 3  : when the decompressed size field isn't available, the upper-bound for that frame is calculated by:
               upper-bound = # blocks * min(128 KB, Window_Size)
  
-
    
+

    
 
 
    size_t ZSTD_frameHeaderSize(const void* src, size_t srcSize);
 
      srcSize must be >= ZSTD_FRAMEHEADERSIZE_PREFIX.
@@ -1017,7 +992,7 @@ size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
            or an error code (if srcSize is too small) 
 

    
 
-
    Memory management
    
+
    Memory management
    
 
 
    size_t ZSTD_estimateCCtxSize(int compressionLevel);
 size_t ZSTD_estimateCCtxSize_usingCParams(ZSTD_compressionParameters cParams);
@@ -1097,7 +1072,7 @@ static ZSTD_customMem const ZSTD_defaultCMem = { NULL, NULL, NULL };  /**< t
  
 

    
 
-
    Advanced compression functions
    
+
    Advanced compression functions
    
 
 
    ZSTD_CDict* ZSTD_createCDict_byReference(const void* dictBuffer, size_t dictSize, int compressionLevel);
 
      Create a digested dictionary for compression
@@ -1242,7 +1217,7 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
  
 

    
 
-
    Advanced decompression functions
    
+
    Advanced decompression functions
    
 
 
    unsigned ZSTD_isFrame(const void* buffer, size_t size);
 
      Tells if the content of `buffer` starts with a valid Frame Identifier.
@@ -1304,7 +1279,7 @@ size_t ZSTD_freeCCtxParams(ZSTD_CCtx_params* params);
  
 

    
 
-
    Advanced streaming functions
      Warning : most of these functions are now redundant with the Advanced API.
+
    Advanced streaming functions
      Warning : most of these functions are now redundant with the Advanced API.
   Once Advanced API reaches "stable" status,
   redundant functions will be deprecated, and then at some point removed.
 
    
@@ -1433,14 +1408,14 @@ size_t ZSTD_initDStream_usingDDict(ZSTD_DStream* zds, const ZSTD_DDict* ddict);
  */
 size_t ZSTD_resetDStream(ZSTD_DStream* zds);
 

    
-
    Buffer-less and synchronous inner streaming functions
    +
    Buffer-less and synchronous inner streaming functions
       This is an advanced API, giving full control over buffer management, for users which need direct control over memory.
   But it's also a complex one, with several restrictions, documented below.
   Prefer normal streaming API for an easier experience.
  
 
    
 
-
    Buffer-less streaming compression (synchronous mode)
    +
    Buffer-less streaming compression (synchronous mode)
       A ZSTD_CCtx object is required to track streaming operations.
   Use ZSTD_createCCtx() / ZSTD_freeCCtx() to manage resource.
   ZSTD_CCtx object can be re-used multiple times within successive compression operations.
@@ -1476,7 +1451,7 @@ size_t ZSTD_compressBegin_usingCDict(ZSTD_CCtx* cctx, const ZSTD_CDict* cdict);
 size_t ZSTD_compressBegin_usingCDict_advanced(ZSTD_CCtx* const cctx, const ZSTD_CDict* const cdict, ZSTD_frameParameters const fParams, unsigned long long const pledgedSrcSize);   /* compression parameters are already set within cdict. pledgedSrcSize must be correct. If srcSize is not known, use macro ZSTD_CONTENTSIZE_UNKNOWN */
 size_t ZSTD_copyCCtx(ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx, unsigned long long pledgedSrcSize); /**<  note: if pledgedSrcSize is not known, use ZSTD_CONTENTSIZE_UNKNOWN */
 

    
-
    Buffer-less streaming decompression (synchronous mode)
    +
    Buffer-less streaming decompression (synchronous mode)
       A ZSTD_DCtx object is required to track streaming operations.
   Use ZSTD_createDCtx() / ZSTD_freeDCtx() to manage it.
   A ZSTD_DCtx object can be re-used multiple times.
@@ -1558,23 +1533,21 @@ typedef struct {
     unsigned checksumFlag;
 } ZSTD_frameHeader;
 

    
-
    ZSTD_getFrameHeader() :
      decode Frame Header, or requires larger `srcSize`.
+
    size_t ZSTD_getFrameHeader(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize);   /**< doesn't consume input */
+/*! ZSTD_getFrameHeader_advanced() :
+ *  same as ZSTD_getFrameHeader(),
+ *  with added capability to select a format (like ZSTD_f_zstd1_magicless) */
+size_t ZSTD_getFrameHeader_advanced(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize, ZSTD_format_e format);
+size_t ZSTD_decodingBufferSize_min(unsigned long long windowSize, unsigned long long frameContentSize);  /**< when frame content size is not known, pass in frameContentSize == ZSTD_CONTENTSIZE_UNKNOWN */
+
      decode Frame Header, or requires larger `srcSize`.
  @return : 0, `zfhPtr` is correctly filled,
           >0, `srcSize` is too small, value is wanted `srcSize` amount,
            or an error code, which can be tested using ZSTD_isError() 
-
    
-
-
    size_t ZSTD_getFrameHeader(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize);   /**< doesn't consume input */
-

    
-
    size_t ZSTD_getFrameHeader_advanced(ZSTD_frameHeader* zfhPtr, const void* src, size_t srcSize, ZSTD_format_e format);
-size_t ZSTD_decodingBufferSize_min(unsigned long long windowSize, unsigned long long frameContentSize);  /**< when frame content size is not known, pass in frameContentSize == ZSTD_CONTENTSIZE_UNKNOWN */
-
      same as ZSTD_getFrameHeader(),
-  with added capability to select a format (like ZSTD_f_zstd1_magicless) 
 

    
 
 
    typedef enum { ZSTDnit_frameHeader, ZSTDnit_blockHeader, ZSTDnit_block, ZSTDnit_lastBlock, ZSTDnit_checksum, ZSTDnit_skippableFrame } ZSTD_nextInputType_e;
 

    
-
    Block level API
    
+
    Block level API
    
 
 
        Frame metadata cost is typically ~18 bytes, which can be non-negligible for very small blocks (< 100 bytes).
     User will have to take in charge required information to regenerate data, such as compressed and content sizes.
diff --git a/lib/zstd.h b/lib/zstd.h
index 3ede0441a..0cc72b4e4 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -82,16 +82,16 @@ ZSTDLIB_API unsigned ZSTD_versionNumber(void);   /**< to check runtime library v
 #define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION)
 ZSTDLIB_API const char* ZSTD_versionString(void);   /* requires v1.3.0+ */
 
-/***************************************
-*  Default constant
-***************************************/
+/* *************************************
+ *  Default constant
+ ***************************************/
 #ifndef ZSTD_CLEVEL_DEFAULT
 #  define ZSTD_CLEVEL_DEFAULT 3
 #endif
 
-/***************************************
-*  Constants
-***************************************/
+/* *************************************
+ *  Constants
+ ***************************************/
 
 /* All magic numbers are supposed read/written to/from files/memory using little-endian convention */
 #define ZSTD_MAGICNUMBER            0xFD2FB528    /* valid since v0.8.0 */
@@ -675,7 +675,7 @@ ZSTDLIB_API size_t ZSTD_CStreamInSize(void);    /**< recommended size for input
 ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output buffer. Guarantee to successfully flush at least one complete compressed block. */
 
 
-/*******************************************************************************
+/* *****************************************************************************
  * This following is a legacy streaming API.
  * It can be replaced by ZSTD_CCtx_reset() and ZSTD_compressStream2().
  * It is redundant, but remains fully supported.
@@ -683,7 +683,7 @@ ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output
  * new API.
  ******************************************************************************/
 
-/**
+/*!
  * Equivalent to:
  *
  *     ZSTD_CCtx_reset(zcs, ZSTD_reset_session_only);
@@ -691,16 +691,16 @@ ZSTDLIB_API size_t ZSTD_CStreamOutSize(void);   /**< recommended size for output
  *     ZSTD_CCtx_setParameter(zcs, ZSTD_c_compressionLevel, compressionLevel);
  */
 ZSTDLIB_API size_t ZSTD_initCStream(ZSTD_CStream* zcs, int compressionLevel);
-/**
+/*!
  * Alternative for ZSTD_compressStream2(zcs, output, input, ZSTD_e_continue).
  * NOTE: The return value is different. ZSTD_compressStream() returns a hint for
  * the next read size (if non-zero and not an error). ZSTD_compressStream2()
  * returns the minimum nb of bytes left to flush (if non-zero and not an error).
  */
 ZSTDLIB_API size_t ZSTD_compressStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
-/** Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush). */
+/*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_flush). */
 ZSTDLIB_API size_t ZSTD_flushStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
-/** Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_end). */
+/*! Equivalent to ZSTD_compressStream2(zcs, output, &emptyInput, ZSTD_e_end). */
 ZSTDLIB_API size_t ZSTD_endStream(ZSTD_CStream* zcs, ZSTD_outBuffer* output);
 
 
@@ -985,7 +985,7 @@ ZSTDLIB_API size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
 #endif  /* ZSTD_H_235446 */
 
 
-/****************************************************************************************
+/* **************************************************************************************
  *   ADVANCED AND EXPERIMENTAL FUNCTIONS
  ****************************************************************************************
  * The definitions in the following section are considered experimental.
@@ -1178,7 +1178,7 @@ typedef enum {
  *            however it does mean that all frame data must be present and valid. */
 ZSTDLIB_API unsigned long long ZSTD_findDecompressedSize(const void* src, size_t srcSize);
 
-/** ZSTD_decompressBound() :
+/*! ZSTD_decompressBound() :
  *  `src` should point to the start of a series of ZSTD encoded and/or skippable frames
  *  `srcSize` must be the _exact_ size of this series
  *       (i.e. there should be a frame boundary at `src + srcSize`)
@@ -1859,7 +1859,7 @@ typedef struct {
     unsigned checksumFlag;
 } ZSTD_frameHeader;
 
-/** ZSTD_getFrameHeader() :
+/*! ZSTD_getFrameHeader() :
  *  decode Frame Header, or requires larger `srcSize`.
  * @return : 0, `zfhPtr` is correctly filled,
  *          >0, `srcSize` is too small, value is wanted `srcSize` amount,