From b3af1873a0b50c1d3545da53786b15f998dd54f7 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Tue, 4 Jun 2019 10:35:40 -0700 Subject: [PATCH] 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 bad5f7b9..024c10e6 100644 --- a/doc/zstd_manual.html +++ b/doc/zstd_manual.html @@ -10,37 +10,27 @@
  1. Introduction
  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

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 3ede0441..0cc72b4e 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,