updated comments

5 files changed, 76 insertions, 66 deletions

diff --git a/lib/Makefile b/lib/Makefile
index bd47ee3..f7d7f72 100644
--- a/lib/Makefile
+++ b/lib/Makefile
@@ -46,7 +46,9 @@ DESTDIR?=
 PREFIX ?= /usr/local
 CPPFLAGS= -DXXH_NAMESPACE=LZ4_ -DLZ4_DLL_EXPORT=1
 CFLAGS ?= -O3
-CFLAGS += -Wall -Wextra -Wundef -Wshadow -Wcast-align -Wcast-qual -Wstrict-prototypes
+CFLAGS += -Wall -Wextra -Wcast-qual -Wcast-align -Wshadow -Wstrict-aliasing=1 \
+          -Wswitch-enum -Wdeclaration-after-statement -Wstrict-prototypes -Wundef \
+          -Wpointer-arith
 FLAGS   = $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
 
 LIBDIR?= $(PREFIX)/lib
diff --git a/lib/lz4.c b/lib/lz4.c
index 5b7d71f..6a6aaf2 100644
--- a/lib/lz4.c
+++ b/lib/lz4.c
@@ -85,9 +85,10 @@
 
 
 /*-************************************
-*  Includes
+*  Dependency
 **************************************/
 #include "lz4.h"
+/* see also "memory routines" below */
 
 
 /*-************************************
@@ -99,15 +100,13 @@
 #  pragma warning(disable : 4127)        /* disable: C4127: conditional expression is constant */
 #  pragma warning(disable : 4293)        /* disable: C4293: too large shift (32-bits) */
 #else
-#  if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)   /* C99 */
-#    if defined(__GNUC__) || defined(__clang__)
-#      define FORCE_INLINE static inline __attribute__((always_inline))
-#    else
-#      define FORCE_INLINE static inline
-#    endif
+#  if defined(__GNUC__) || defined(__clang__)
+#    define FORCE_INLINE static inline __attribute__((always_inline))
+#  elif defined(__cplusplus) || (defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */)
+#    define FORCE_INLINE static inline
 #  else
 #    define FORCE_INLINE static
-#  endif   /* __STDC_VERSION__ */
+#  endif
 #endif  /* _MSC_VER */
 
 /* LZ4_GCC_VERSION is defined into lz4.h */
@@ -134,7 +133,7 @@
 /*-************************************
 *  Basic Types
 **************************************/
-#if defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)   /* C99 */
+#if defined(__cplusplus) || (defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */)
 # include <stdint.h>
   typedef  uint8_t BYTE;
   typedef uint16_t U16;
@@ -165,6 +164,7 @@ static unsigned LZ4_isLittleEndian(void)
 
 
 #if defined(LZ4_FORCE_MEMORY_ACCESS) && (LZ4_FORCE_MEMORY_ACCESS==2)
+/* lie to the compiler about data alignment; use with caution */
 
 static U16 LZ4_read16(const void* memPtr) { return *(const U16*) memPtr; }
 static U32 LZ4_read32(const void* memPtr) { return *(const U32*) memPtr; }
@@ -186,7 +186,7 @@ static size_t LZ4_read_ARCH(const void* ptr) { return ((const unalign*)ptr)->uAr
 static void LZ4_write16(void* memPtr, U16 value) { ((unalign*)memPtr)->u16 = value; }
 static void LZ4_write32(void* memPtr, U32 value) { ((unalign*)memPtr)->u32 = value; }
 
-#else
+#else  /* safe and portable access through memcpy() */
 
 static U16 LZ4_read16(const void* memPtr)
 {
@@ -242,7 +242,7 @@ static void LZ4_copy8(void* dst, const void* src)
     memcpy(dst,src,8);
 }
 
-/* customized variant of memcpy, which can overwrite up to 7 bytes beyond dstEnd */
+/* customized variant of memcpy, which can overwrite up to 8 bytes beyond dstEnd */
 static void LZ4_wildCopy(void* dstPtr, const void* srcPtr, void* dstEnd)
 {
     BYTE* d = (BYTE*)dstPtr;
@@ -354,7 +354,7 @@ static unsigned LZ4_count(const BYTE* pIn, const BYTE* pMatch, const BYTE* pInLi
     const BYTE* const pStart = pIn;
 
     while (likely(pIn<pInLimit-(STEPSIZE-1))) {
-        size_t diff = LZ4_read_ARCH(pMatch) ^ LZ4_read_ARCH(pIn);
+        size_t const diff = LZ4_read_ARCH(pMatch) ^ LZ4_read_ARCH(pIn);
         if (!diff) { pIn+=STEPSIZE; pMatch+=STEPSIZE; continue; }
         pIn += LZ4_NbCommonBytes(diff);
         return (unsigned)(pIn - pStart);
@@ -1475,4 +1475,3 @@ int LZ4_decompress_fast_withPrefix64k(const char* source, char* dest, int origin
 }
 
 #endif   /* LZ4_COMMONDEFS_ONLY */
-
diff --git a/lib/lz4frame.c b/lib/lz4frame.c
index 6bb76a1..2ecb66b 100644
--- a/lib/lz4frame.c
+++ b/lib/lz4frame.c
@@ -213,6 +213,8 @@ const char* LZ4F_getErrorName(LZ4F_errorCode_t code)
     return codeError;
 }
 
+unsigned LZ4F_getVersion() { return LZ4F_VERSION; }
+
 
 /*-************************************
 *  Private functions
diff --git a/lib/lz4frame.h b/lib/lz4frame.h
index 79164b8..0fb663a 100644
--- a/lib/lz4frame.h
+++ b/lib/lz4frame.h
@@ -34,18 +34,19 @@
 
 /* LZ4F is a stand-alone API to create LZ4-compressed frames
  * conformant with specification v1.5.1.
- * All related operations, including memory management, are handled internally by the library.
- * You don't need lz4.h when using lz4frame.h.
+ * It also offers streaming capabilities.
+ * lz4.h is not required when using lz4frame.h.
  * */
 
-#pragma once
+#ifndef LZ4F_H_09782039843
+#define LZ4F_H_09782039843
 
 #if defined (__cplusplus)
 extern "C" {
 #endif
 
 /*-************************************
-*  Includes
+*  Dependency
 **************************************/
 #include <stddef.h>   /* size_t */
 
@@ -78,7 +79,7 @@ LZ4FLIB_API const char* LZ4F_getErrorName(LZ4F_errorCode_t code);   /* return er
 /*-************************************
 *  Frame compression types
 **************************************/
-//#define LZ4F_DISABLE_OBSOLETE_ENUMS
+/* #define LZ4F_DISABLE_OBSOLETE_ENUMS */  /* uncomment to disable obsolete enums */
 #ifndef LZ4F_DISABLE_OBSOLETE_ENUMS
 #  define LZ4F_OBSOLETE_ENUM(x) ,x
 #else
@@ -136,7 +137,7 @@ typedef struct {
 typedef struct {
   LZ4F_frameInfo_t frameInfo;
   int      compressionLevel;       /* 0 == default (fast mode); values above 16 count as 16; values below 0 count as 0 */
-  unsigned autoFlush;              /* 1 == always flush (reduce need for tmp buffer) */
+  unsigned autoFlush;              /* 1 == always flush (reduce usage of tmp buffer) */
   unsigned reserved[4];            /* must be zero for forward compatibility */
 } LZ4F_preferences_t;
 
@@ -144,55 +145,60 @@ typedef struct {
 /*-*********************************
 *  Simple compression function
 ***********************************/
+/*!LZ4F_compressFrameBound() :
+ * Returns the maximum possible size of a frame given srcSize content and preferences.
+ */
 LZ4FLIB_API size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
 
 /*!LZ4F_compressFrame() :
  * Compress an entire srcBuffer into a valid LZ4 frame, as defined by specification v1.5.1
- * The most important rule is that dstBuffer MUST be large enough (dstMaxSize) to ensure compression completion even in worst case.
- * You can get the minimum value of dstMaxSize by using LZ4F_compressFrameBound()
- * If this condition is not respected, LZ4F_compressFrame() will fail (result is an errorCode)
+ * An important rule is that dstBuffer MUST be large enough (dstCapacity) to store the result in worst case situation.
+ * This value is supplied by LZ4F_compressFrameBound().
+ * If this condition is not respected, LZ4F_compressFrame() will fail (result is an errorCode).
  * The LZ4F_preferences_t structure is optional : you can provide NULL as argument. All preferences will be set to default.
- * The result of the function is the number of bytes written into dstBuffer.
- * The function outputs an error code if it fails (can be tested using LZ4F_isError())
+ * @return : number of bytes written into dstBuffer.
+ *           or an error code if it fails (can be tested using LZ4F_isError())
  */
-LZ4FLIB_API size_t LZ4F_compressFrame(void* dstBuffer, size_t dstMaxSize, const void* srcBuffer, size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
+LZ4FLIB_API size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
 
 
 
 /*-***********************************
 *  Advanced compression functions
 *************************************/
-typedef struct LZ4F_cctx_s* LZ4F_compressionContext_t;   /* must be aligned on 8-bytes */
+typedef struct LZ4F_cctx_s LZ4F_cctx;   /* incomplete type */
+typedef LZ4F_cctx* LZ4F_compressionContext_t;   /* for compatibility with previous API version */
 
 typedef struct {
-  unsigned stableSrc;    /* 1 == src content will remain available on future calls to LZ4F_compress(); avoid saving src content within tmp buffer as future dictionary */
+  unsigned stableSrc;    /* 1 == src content remain present on future calls to LZ4F_compress(); avoid saving src content within tmp buffer as future dictionary */
   unsigned reserved[3];
 } LZ4F_compressOptions_t;
 
 /* Resource Management */
 
 #define LZ4F_VERSION 100
-LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_compressionContext_t* cctxPtr, unsigned version);
-LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_compressionContext_t cctx);
+LZ4FLIB_API unsigned LZ4F_getVersion();
+LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
+LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
 /* LZ4F_createCompressionContext() :
  * The first thing to do is to create a compressionContext object, which will be used in all compression operations.
  * This is achieved using LZ4F_createCompressionContext(), which takes as argument a version and an LZ4F_preferences_t structure.
- * The version provided MUST be LZ4F_VERSION. It is intended to track potential version differences between different binaries.
- * The function will provide a pointer to a fully allocated LZ4F_compressionContext_t object.
- * If the result LZ4F_errorCode_t is not zero, there was an error during context creation.
+ * The version provided MUST be LZ4F_VERSION. It is intended to track potential version mismatch, notably when using DLL.
+ * The function will provide a pointer to a fully allocated LZ4F_cctx object.
+ * If @return != zero, there was an error during context creation.
  * Object can release its memory using LZ4F_freeCompressionContext();
  */
 
 
 /* Compression */
 
-LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_compressionContext_t cctx, void* dstBuffer, size_t dstMaxSize, const LZ4F_preferences_t* prefsPtr);
+LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr);
 /* LZ4F_compressBegin() :
  * will write the frame header into dstBuffer.
- * dstBuffer must be large enough to accommodate a header (dstMaxSize). Maximum header size is 15 bytes.
- * The LZ4F_preferences_t structure is optional : you can provide NULL as argument, all preferences will then be set to default.
- * The result of the function is the number of bytes written into dstBuffer for the header
- * or an error code (can be tested using LZ4F_isError())
+ * dstBuffer must be large enough to accommodate a header. Maximum header size is 15 bytes.
+ * `prefsPtr` is optional : you can provide NULL as argument, all preferences will then be set to default.
+ * @return : number of bytes written into dstBuffer for the header
+ *           or an error code (which can be tested using LZ4F_isError())
  */
 
 LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
@@ -203,38 +209,37 @@ LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t*
  * This function includes frame termination cost (4 bytes, or 8 if frame checksum is enabled)
  */
 
-LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_compressionContext_t cctx, void* dstBuffer, size_t dstMaxSize, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* cOptPtr);
-/* LZ4F_compressUpdate()
+LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* cOptPtr);
+/* LZ4F_compressUpdate() :
  * LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary.
- * The most important rule is that dstBuffer MUST be large enough (dstMaxSize) to ensure compression completion even in worst case.
- * You can get the minimum value of dstMaxSize by using LZ4F_compressBound().
+ * An important rule is that dstBuffer MUST be large enough (dstCapacity) to ensure compression completion even in worst case.
+ * This value is provided by using LZ4F_compressBound().
  * If this condition is not respected, LZ4F_compress() will fail (result is an errorCode).
- * LZ4F_compressUpdate() doesn't guarantee error recovery, so you have to reset compression context when an error occurs.
- * The LZ4F_compressOptions_t structure is optional : you can provide NULL as argument.
- * The result of the function is the number of bytes written into dstBuffer : it can be zero, meaning input data was just buffered.
- * The function outputs an error code if it fails (can be tested using LZ4F_isError())
+ * LZ4F_compressUpdate() doesn't guarantee error recovery. When an error occurs, compression context must be freed or resized.
+ * `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default.
+ * @return : number of bytes written into `dstBuffer` (it can be zero, meaning input data was just buffered).
+ *           or an error code if it fails (which can be tested using LZ4F_isError())
  */
 
-LZ4FLIB_API size_t LZ4F_flush(LZ4F_compressionContext_t cctx, void* dstBuffer, size_t dstMaxSize, const LZ4F_compressOptions_t* cOptPtr);
-/* LZ4F_flush()
- * Should you need to generate compressed data immediately, without waiting for the current block to be filled,
- * you can call LZ4_flush(), which will immediately compress any remaining data buffered within cctx.
- * Note that dstMaxSize must be large enough to ensure the operation will be successful.
- * LZ4F_compressOptions_t structure is optional : you can provide NULL as argument.
- * The result of the function is the number of bytes written into dstBuffer
- * (it can be zero, this means there was no data left within cctx)
- * The function outputs an error code if it fails (can be tested using LZ4F_isError())
+LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);
+/* LZ4F_flush() :
+ * When data must be generated and sent immediately, without waiting for a block to be completely filled,
+ * it's possible to call LZ4_flush(). It will immediately compress any data buffered within cctx.
+ * `dstCapacity` must be large enough to ensure the operation will be successful.
+ * `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default.
+ * @return : number of bytes written into dstBuffer (it can be zero, which means there was no data stored within cctx)
+ *           or an error code if it fails (which can be tested using LZ4F_isError())
  */
 
-LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_compressionContext_t cctx, void* dstBuffer, size_t dstMaxSize, const LZ4F_compressOptions_t* cOptPtr);
-/* LZ4F_compressEnd()
- * When you want to properly finish the compressed frame, just call LZ4F_compressEnd().
- * It will flush whatever data remained within compressionContext (like LZ4_flush())
- * but also properly finalize the frame, with an endMark and a checksum.
- * The result of the function is the number of bytes written into dstBuffer (necessarily >= 4 (endMark), or 8 if optional frame checksum is enabled)
- * The function outputs an error code if it fails (can be tested using LZ4F_isError())
- * The LZ4F_compressOptions_t structure is optional : you can provide NULL as argument.
- * A successful call to LZ4F_compressEnd() makes cctx available again for next compression task.
+LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstMaxSize, const LZ4F_compressOptions_t* cOptPtr);
+/* LZ4F_compressEnd() :
+ * To properly finish the compressed frame, invoke LZ4F_compressEnd().
+ * It will flush whatever data remained within `cctx` (like LZ4_flush())
+ * and properly finalize the frame, with an endMark and a checksum.
+ * `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default.
+ * @return : number of bytes written into dstBuffer (necessarily >= 4 (endMark), or 8 if optional frame checksum is enabled)
+ *           or an error code if it fails (which can be tested using LZ4F_isError())
+ * A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task.
  */
 
 
@@ -317,3 +322,5 @@ LZ4FLIB_API size_t LZ4F_decompress(LZ4F_decompressionContext_t dctx,
 #if defined (__cplusplus)
 }
 #endif
+
+#endif  /* LZ4F_H_09782039843 */
diff --git a/lib/lz4hc.c b/lib/lz4hc.c
index a1d1a55..f109622 100644
--- a/lib/lz4hc.c
+++ b/lib/lz4hc.c
@@ -108,7 +108,7 @@ typedef struct
 *  Local Macros
 **************************************/
 #define HASH_FUNCTION(i)       (((i) * 2654435761U) >> ((MINMATCH*8)-HASH_LOG))
-//#define DELTANEXTU16(p)        chainTable[(p) & MAXD_MASK]   /* flexible, MAXD dependent */
+/* #define DELTANEXTU16(p)        chainTable[(p) & MAXD_MASK] */   /* flexible, MAXD dependent */
 #define DELTANEXTU16(p)        chainTable[(U16)(p)]   /* faster */
 
 static U32 LZ4HC_hashPtr(const void* ptr) { return HASH_FUNCTION(LZ4_read32(ptr)); }
@@ -252,7 +252,7 @@ FORCE_INLINE int LZ4HC_InsertAndGetWiderMatch (
                 }
             }
         } else {
-            const BYTE* matchPtr = dictBase + matchIndex;
+            const BYTE* const matchPtr = dictBase + matchIndex;
             if (LZ4_read32(matchPtr) == LZ4_read32(ip)) {
                 size_t mlt;
                 int back=0;