minor comments refactoring

lib/zstd.h

@@ -1,7 +1,7 @@
 /*
     zstd - standard compression library
     Header File
-    Copyright (C) 2014-2015, Yann Collet.
+    Copyright (C) 2014-2016, Yann Collet.
 
     BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
 
@@ -28,7 +28,6 @@
 
     You can contact the author at :
     - zstd source repository : https://github.com/Cyan4973/zstd
-    - ztsd public forum : https://groups.google.com/forum/#!forum/lz4c
 */
 #ifndef ZSTD_H
 #define ZSTD_H
@@ -37,13 +36,13 @@
 extern "C" {
 #endif
 
-/* *************************************
-*  Includes
+/*-*************************************
+*  Dependencies
 ***************************************/
 #include <stddef.h>   /* size_t */
 
 
-/* ***************************************************************
+/*-***************************************************************
 *  Export parameters
 *****************************************************************/
 /*!
@@ -70,43 +69,39 @@ ZSTDLIB_API unsigned ZSTD_versionNumber (void);
 /* *************************************
 *  Simple functions
 ***************************************/
+/*! ZSTD_compress() :
+    Compresses `srcSize` bytes from buffer `src` into buffer `dst` of size `dstCapacity`.
+    Destination buffer must be already allocated.
+    Compression runs faster if `dstCapacity` >=  `ZSTD_compressBound(srcSize)`.
+    @return : the number of bytes written into `dst`,
+              or an error code if it fails (which can be tested using ZSTD_isError()) */
 ZSTDLIB_API size_t ZSTD_compress(   void* dst, size_t dstCapacity,
                               const void* src, size_t srcSize,
                                      int  compressionLevel);
 
+/*! ZSTD_decompress() :
+    `compressedSize` : is the _exact_ size of the compressed blob, otherwise decompression will fail.
+    `dstCapacity` must be large enough, equal or larger than originalSize.
+    @return : the number of bytes decompressed into `dst` (<= `dstCapacity`),
+              or an errorCode if it fails (which can be tested using ZSTD_isError()) */
 ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity,
                               const void* src, size_t compressedSize);
 
-/**
-ZSTD_compress() :
-    Compresses @srcSize bytes from buffer @src into buffer @dst of size @dstCapacity.
-    Destination buffer must be already allocated.
-    Compression runs faster if @dstCapacity >=  ZSTD_compressBound(srcSize).
-    @return : the number of bytes written into @dst
-              or an error code if it fails (which can be tested using ZSTD_isError())
-
-ZSTD_decompress() :
-    @compressedSize : is the _exact_ size of the compressed blob (or decompression will fail)
-    @dst must be large enough, equal or larger than originalSize.
-    @return : the number of bytes decompressed into @dst (<= @dstCapacity)
-              or an errorCode if it fails (which can be tested using ZSTD_isError())
-*/
-
 
 /* *************************************
-*  Tool functions
+*  Helper functions
 ***************************************/
-ZSTDLIB_API size_t      ZSTD_compressBound(size_t srcSize);   /** maximum compressed size (worst case scenario) */
+ZSTDLIB_API size_t      ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size (worst case scenario) */
 
 /* Error Management */
-ZSTDLIB_API unsigned    ZSTD_isError(size_t code);         /** tells if a return value is an error code */
-ZSTDLIB_API const char* ZSTD_getErrorName(size_t code);    /** provides error code string */
+ZSTDLIB_API unsigned    ZSTD_isError(size_t code);          /*!< tells if a `size_t` function result is an error code */
+ZSTDLIB_API const char* ZSTD_getErrorName(size_t code);     /*!< provides readable string for an error code */
 
 
 /* *************************************
 *  Explicit memory management
 ***************************************/
-/** Compression context management */
+/** Compression context */
 typedef struct ZSTD_CCtx_s ZSTD_CCtx;   /* incomplete type */
 ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void);
 ZSTDLIB_API size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);
@@ -115,12 +110,12 @@ ZSTDLIB_API size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);
     Same as ZSTD_compress(), but requires an already allocated ZSTD_CCtx (see ZSTD_createCCtx()) */
 ZSTDLIB_API size_t ZSTD_compressCCtx(ZSTD_CCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, int compressionLevel);
 
-/** Decompression context management */
+/** Decompression context */
 typedef struct ZSTD_DCtx_s ZSTD_DCtx;
 ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void);
 ZSTDLIB_API size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);
 
-/** ZSTD_decompressDCtx
+/** ZSTD_decompressDCtx() :
 *   Same as ZSTD_decompress(), but requires an already allocated ZSTD_DCtx (see ZSTD_createDCtx()) */
 ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
 
@@ -128,9 +123,8 @@ ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* ctx, void* dst, size_t dstCapa
 /*-***********************
 *  Dictionary API
 *************************/
-
-/*! ZSTD_compress_usingDict
-*   Compression using a pre-defined Dictionary content (see dictBuilder)
+/*! ZSTD_compress_usingDict() :
+*   Compression using a pre-defined Dictionary content (see dictBuilder).
 *   Note : dict can be NULL, in which case, it's equivalent to ZSTD_compressCCtx() */
 ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,
                                            void* dst, size_t dstCapacity,
@@ -138,9 +132,9 @@ ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,
                                      const void* dict,size_t dictSize,
                                            int compressionLevel);
 
-/*! ZSTD_decompress_usingDict
-*   Decompression using a pre-defined Dictionary content (see dictBuilder)
-*   Dictionary must be identical to the one used during compression, otherwise regenerated data will be corrupted
+/*! ZSTD_decompress_usingDict() :
+*   Decompression using a pre-defined Dictionary content (see dictBuilder).
+*   Dictionary must be identical to the one used during compression, otherwise regenerated data will be corrupted.
 *   Note : dict can be NULL, in which case, it's equivalent to ZSTD_decompressDCtx() */
 ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx,
                                              void* dst, size_t dstCapacity,