Merge pull request #307 from inikep/dev

lz4frame manual

10 files changed, 446 insertions, 143 deletions

diff --git a/Makefile b/Makefile
index 1432e6b..efcf28f 100644
--- a/Makefile
+++ b/Makefile
@@ -3,6 +3,8 @@
 # Copyright (C) Yann Collet 2011-2016
 # All rights reserved.
 #
+# This Makefile is validated for Linux, macOS, *BSD, Hurd, Solaris, MSYS2 targets
+#
 # BSD license
 # Redistribution and use in source and binary forms, with or without modification,
 # are permitted provided that the following conditions are met:
diff --git a/contrib/gen_manual/gen-lz4-manual.sh b/contrib/gen_manual/gen-lz4-manual.sh
index 55d31a4..73a7214 100644
--- a/contrib/gen_manual/gen-lz4-manual.sh
+++ b/contrib/gen_manual/gen-lz4-manual.sh
@@ -6,4 +6,5 @@ LIBVER_PATCH_SCRIPT=`sed -n '/define LZ4_VERSION_RELEASE/s/.*[[:blank:]]\([0-9][
 LIBVER_SCRIPT=$LIBVER_MAJOR_SCRIPT.$LIBVER_MINOR_SCRIPT.$LIBVER_PATCH_SCRIPT
 
 echo LZ4_VERSION=$LIBVER_SCRIPT
-./gen_manual $LIBVER_SCRIPT ../../lib/lz4.h ./lz4_manual.html
+./gen_manual "lz4 $LIBVER_SCRIPT" ../../lib/lz4.h ./lz4_manual.html
+./gen_manual "lz4frame $LIBVER_SCRIPT" ../../lib/lz4frame.h ./lz4frame_manual.html
diff --git a/contrib/gen_manual/gen_manual.cpp b/contrib/gen_manual/gen_manual.cpp
index 2df081d..65abd3a 100644
--- a/contrib/gen_manual/gen_manual.cpp
+++ b/contrib/gen_manual/gen_manual.cpp
@@ -89,11 +89,13 @@ vector<string> get_lines(vector<string>& input, int& linenum, string terminator)
 /* print line with LZ4LIB_API removed and C++ comments not bold */
 void print_line(stringstream &sout, string line)
 {
-    size_t spos;
+    size_t spos, epos;
 
     if (line.substr(0,11) == "LZ4LIB_API ") line = line.substr(11);
+    if (line.substr(0,12) == "LZ4FLIB_API ") line = line.substr(12);
     spos = line.find("/*");
-    if (spos!=string::npos) {
+    epos = line.find("*/");
+    if (spos!=string::npos && epos!=string::npos) {
         sout << line.substr(0, spos);
         sout << "</b>" << line.substr(spos) << "<b>" << endl;
     } else {
@@ -118,7 +120,7 @@ int main(int argc, char *argv[]) {
         return 1;
     }
 
-    version = "lz4 " + string(argv[1]) + " Manual";
+    version = string(argv[1]) + " Manual";
 
     istream.open(argv[2], ifstream::in);
     if (!istream.is_open()) {
@@ -158,36 +160,28 @@ int main(int argc, char *argv[]) {
             continue;
         }
 
-        /* comments of type /*= and /**= mean: use a <H3> header and show also all functions until first empty line */
-        if ((line.substr(0,3) == "/*=" || line.substr(0,4) == "/**=") && line.find("*/")!=string::npos) {
-            trim_comments(line);
-            trim(line, "= ");
-            sout << "<h3>" << line << "</h3><pre><b>";
-            lines = get_lines(input, ++linenum, "");
-            for (l=0; l<lines.size(); l++) {
-                print_line(sout, lines[l]);
-            }
-            sout << "</b></pre><BR>" << endl;
-            continue;
+        spos = line.find("/**=");
+        if (spos==string::npos) {
+            spos = line.find("/*!");
+            if (spos==string::npos)
+                spos = line.find("/**");
+            if (spos==string::npos)
+                spos = line.find("/*-");
+            if (spos==string::npos)
+                spos = line.find("/*=");
+            if (spos==string::npos)
+                continue;
+            exclam = line[spos+2];
         }
+        else exclam = '=';
 
-        spos = line.find("/*!");
-        if (spos==string::npos)
-            spos = line.find("/**");
-        if (spos==string::npos)
-            spos = line.find("/*-");
-
-        if (spos==string::npos)
-            continue;
-
-        exclam = line[spos+2];
         comments = get_lines(input, linenum, "*/");
         if (!comments.empty()) comments[0] = line.substr(spos+3);
         if (!comments.empty()) comments[comments.size()-1] = comments[comments.size()-1].substr(0, comments[comments.size()-1].find("*/"));
         for (l=0; l<comments.size(); l++) {
             if (comments[l].find(" *")==0) comments[l] = comments[l].substr(2);
             else if (comments[l].find("  *")==0) comments[l] = comments[l].substr(3);
-            trim(comments[l], "*-");
+            trim(comments[l], "*-=");
         }
         while (!comments.empty() && comments[comments.size()-1].empty()) comments.pop_back(); // remove empty line at the end
         while (!comments.empty() && comments[0].empty()) comments.erase(comments.begin()); // remove empty line at the start
@@ -208,6 +202,18 @@ int main(int argc, char *argv[]) {
                 print_line(sout, comments[l]);
             }
             sout << "</p></pre><BR>" << endl << endl;
+        } else if (exclam == '=') { /* comments of type /*= and /**= mean: use a <H3> header and show also all functions until first empty line */
+            trim(comments[0], " ");
+            sout << "<h3>" << comments[0] << "</h3><pre>";
+            for (l=1; l<comments.size(); l++) {
+                print_line(sout, comments[l]);
+            }
+            sout << "</pre><b><pre>";
+            lines = get_lines(input, ++linenum, "");
+            for (l=0; l<lines.size(); l++) {
+                print_line(sout, lines[l]);
+            }
+            sout << "</pre></b><BR>" << endl;
         } else { /* comments of type /** and /*- mean: this is a comment; use a <H2> header for the first line */
             if (comments.empty()) continue;
 
@@ -238,4 +244,4 @@ int main(int argc, char *argv[]) {
     ostream << "</html>" << endl << "</body>" << endl;
 
     return 0;
-}
+}
\ No newline at end of file
diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html
index bc46645..ff6e149 100644
--- a/doc/lz4_manual.html
+++ b/doc/lz4_manual.html
@@ -1,20 +1,22 @@
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>lz4 1.7.2 Manual</title>
+<title>lz4 1.7.5 Manual</title>
 </head>
 <body>
-<h1>lz4 1.7.2 Manual</h1>
+<h1>lz4 1.7.5 Manual</h1>
 <hr>
 <a name="Contents"></a><h2>Contents</h2>
 <ol>
 <li><a href="#Chapter1">Introduction</a></li>
-<li><a href="#Chapter2">Tuning parameter</a></li>
-<li><a href="#Chapter3">Private definitions</a></li>
+<li><a href="#Chapter2">Version</a></li>
+<li><a href="#Chapter3">Tuning parameter</a></li>
 <li><a href="#Chapter4">Simple Functions</a></li>
 <li><a href="#Chapter5">Advanced Functions</a></li>
 <li><a href="#Chapter6">Streaming Compression Functions</a></li>
 <li><a href="#Chapter7">Streaming Decompression Functions</a></li>
+<li><a href="#Chapter8">Private definitions</a></li>
+<li><a href="#Chapter9">Obsolete Functions</a></li>
 </ol>
 <hr>
 <a name="Chapter1"></a><h2>Introduction</h2><pre>
@@ -29,19 +31,26 @@
     - unbounded multiple steps (described as Streaming compression)
 
   lz4.h provides block compression functions. It gives full buffer control to user.
-  Block compression functions are not-enough to send information,
-  since it's still necessary to provide metadata (such as compressed size),
-  and each application can do it in whichever way it wants.
-  For interoperability, there is LZ4 frame specification (doc/lz4_Frame_format.md).
+  Decompressing an lz4-compressed block also requires metadata (such as compressed size).
+  Each application is free to encode such metadata in whichever way it wants.
+
+  An additional format, called LZ4 frame specification (doc/lz4_Frame_format.md),
+  take care of encoding standard metadata alongside LZ4-compressed blocks.
+  If your application requires interoperability, it's recommended to use it.
   A library is provided to take care of it, see lz4frame.h.
 <BR></pre>
 
-<h3>Version</h3><pre><b>int LZ4_versionNumber (void);
-const char* LZ4_versionString (void);
+<a name="Chapter2"></a><h2>Version</h2><pre></pre>
+
+<pre><b>int LZ4_versionNumber (void);  </b>/**< library version number; to be used when checking dll version */<b>
 </b></pre><BR>
-<a name="Chapter2"></a><h2>Tuning parameter</h2><pre></pre>
+<pre><b>const char* LZ4_versionString (void);   </b>/**< library version string; to be used when checking dll version */<b>
+</b></pre><BR>
+<a name="Chapter3"></a><h2>Tuning parameter</h2><pre></pre>
 
-<pre><b>#define LZ4_MEMORY_USAGE 14
+<pre><b>#ifndef LZ4_MEMORY_USAGE
+# define LZ4_MEMORY_USAGE 14
+#endif
 </b><p> Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.)
  Increasing memory usage improves compression ratio
  Reduced memory usage can improve speed, due to cache effect
@@ -49,44 +58,6 @@ const char* LZ4_versionString (void);
  
 </p></pre><BR>
 
-<a name="Chapter3"></a><h2>Private definitions</h2><pre>
- Do not use these definitions.
- They are exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`.
- If you use these definitions in your code, it will break when you upgrade LZ4 to a new version.
-<BR></pre>
-
-<pre><b>typedef struct {
-    uint32_t hashTable[LZ4_HASH_SIZE_U32];
-    uint32_t currentOffset;
-    uint32_t initCheck;
-    const uint8_t* dictionary;
-    uint8_t* bufferStart;   </b>/* obsolete, used for slideInputBuffer */<b>
-    uint32_t dictSize;
-} LZ4_stream_t_internal;
-</b></pre><BR>
-<pre><b>typedef struct {
-    const uint8_t* externalDict;
-    size_t extDictSize;
-    const uint8_t* prefixEnd;
-    size_t prefixSize;
-} LZ4_streamDecode_t_internal;
-</b></pre><BR>
-<pre><b>typedef struct {
-    unsigned int hashTable[LZ4_HASH_SIZE_U32];
-    unsigned int currentOffset;
-    unsigned int initCheck;
-    const unsigned char* dictionary;
-    unsigned char* bufferStart;   </b>/* obsolete, used for slideInputBuffer */<b>
-    unsigned int dictSize;
-} LZ4_stream_t_internal;
-</b></pre><BR>
-<pre><b>typedef struct {
-    const unsigned char* externalDict;
-    size_t extDictSize;
-    const unsigned char* prefixEnd;
-    size_t prefixSize;
-} LZ4_streamDecode_t_internal;
-</b></pre><BR>
 <a name="Chapter4"></a><h2>Simple Functions</h2><pre></pre>
 
 <pre><b>int LZ4_compress_default(const char* source, char* dest, int sourceSize, int maxDestSize);
@@ -178,30 +149,16 @@ int LZ4_compress_fast_extState (void* state, const char* source, char* dest, int
 
 <a name="Chapter6"></a><h2>Streaming Compression Functions</h2><pre></pre>
 
-<pre><b>typedef struct {
-  union {
-    long long table[LZ4_STREAMSIZE_U64];
-    LZ4_stream_t_internal internal_donotuse;
-  };
-} LZ4_stream_t;
-</b><p> information structure to track an LZ4 stream.
- important : init this structure content before first use !
- note : only allocated directly the structure if you are statically linking LZ4
-        If you are using liblz4 as a DLL, please use below construction methods instead.
- 
-</p></pre><BR>
-
-<pre><b>void LZ4_resetStream (LZ4_stream_t* streamPtr);
-</b><p>  Use this function to init an allocated `LZ4_stream_t` structure
- 
-</p></pre><BR>
-
 <pre><b>LZ4_stream_t* LZ4_createStream(void);
 int           LZ4_freeStream (LZ4_stream_t* streamPtr);
 </b><p>  LZ4_createStream() will allocate and initialize an `LZ4_stream_t` structure.
   LZ4_freeStream() releases its memory.
-  In the context of a DLL (liblz4), please use these methods rather than the static struct.
-  They are more future proof, in case of a change of `LZ4_stream_t` size.
+ 
+</p></pre><BR>
+
+<pre><b>void LZ4_resetStream (LZ4_stream_t* streamPtr);
+</b><p>  An LZ4_stream_t structure can be allocated once and re-used multiple times.
+  Use this function to init an allocated `LZ4_stream_t` structure and start a new compression.
  
 </p></pre><BR>
 
@@ -231,24 +188,12 @@ int           LZ4_freeStream (LZ4_stream_t* streamPtr);
  
 </p></pre><BR>
 
-<a name="Chapter7"></a><h2>Streaming Decompression Functions</h2><pre></pre>
+<a name="Chapter7"></a><h2>Streaming Decompression Functions</h2><pre>  Bufferless synchronous API
+<BR></pre>
 
-<pre><b>typedef struct {
-  union {
-    unsigned long long table[LZ4_STREAMDECODESIZE_U64];
-    LZ4_streamDecode_t_internal internal_donotuse;
-  };
-</b></pre><BR>
 <pre><b>LZ4_streamDecode_t* LZ4_createStreamDecode(void);
 int                 LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
-</b><p> information structure to track an LZ4 stream.
- init this structure content using LZ4_setStreamDecode or memset() before first use !
-
- In the context of a DLL (liblz4) please prefer usage of construction methods below.
- They are more future proof, in case of a change of LZ4_streamDecode_t size in the future.
- LZ4_createStreamDecode will allocate and initialize an LZ4_streamDecode_t structure
- LZ4_freeStreamDecode releases its memory.
- 
+</b><p>  creation / destruction of streaming decompression tracking structure 
 </p></pre><BR>
 
 <pre><b>int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize);
@@ -278,10 +223,102 @@ int LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const ch
 
 <pre><b>int LZ4_decompress_safe_usingDict (const char* source, char* dest, int compressedSize, int maxDecompressedSize, const char* dictStart, int dictSize);
 int LZ4_decompress_fast_usingDict (const char* source, char* dest, int originalSize, const char* dictStart, int dictSize);
-</b><p>Advanced decoding functions :
-    These decoding functions work the same as
-    a combination of LZ4_setStreamDecode() followed by LZ4_decompress_x_continue()
-    They are stand-alone. They don't need nor update an LZ4_streamDecode_t structure.
+</b><p>  These decoding functions work the same as
+  a combination of LZ4_setStreamDecode() followed by LZ4_decompress_*_continue()
+  They are stand-alone, and don't need an LZ4_streamDecode_t structure.
+ 
+</p></pre><BR>
+
+<a name="Chapter8"></a><h2>Private definitions</h2><pre>
+ Do not use these definitions.
+ They are exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`.
+ Using these definitions will expose code to API and/or ABI break in future versions of the library.
+<BR></pre>
+
+<pre><b>typedef struct {
+    uint32_t hashTable[LZ4_HASH_SIZE_U32];
+    uint32_t currentOffset;
+    uint32_t initCheck;
+    const uint8_t* dictionary;
+    uint8_t* bufferStart;   </b>/* obsolete, used for slideInputBuffer */<b>
+    uint32_t dictSize;
+} LZ4_stream_t_internal;
+</b></pre><BR>
+<pre><b>typedef struct {
+    const uint8_t* externalDict;
+    size_t extDictSize;
+    const uint8_t* prefixEnd;
+    size_t prefixSize;
+} LZ4_streamDecode_t_internal;
+</b></pre><BR>
+<pre><b>typedef struct {
+    unsigned int hashTable[LZ4_HASH_SIZE_U32];
+    unsigned int currentOffset;
+    unsigned int initCheck;
+    const unsigned char* dictionary;
+    unsigned char* bufferStart;   </b>/* obsolete, used for slideInputBuffer */<b>
+    unsigned int dictSize;
+} LZ4_stream_t_internal;
+</b></pre><BR>
+<pre><b>typedef struct {
+    const unsigned char* externalDict;
+    size_t extDictSize;
+    const unsigned char* prefixEnd;
+    size_t prefixSize;
+} LZ4_streamDecode_t_internal;
+</b></pre><BR>
+<pre><b>#define LZ4_STREAMSIZE_U64 ((1 << (LZ4_MEMORY_USAGE-3)) + 4)
+#define LZ4_STREAMSIZE     (LZ4_STREAMSIZE_U64 * sizeof(unsigned long long))
+union LZ4_stream_u {
+    unsigned long long table[LZ4_STREAMSIZE_U64];
+    LZ4_stream_t_internal internal_donotuse;
+} ;  </b>/* previously typedef'd to LZ4_stream_t */<b>
+</b><p> information structure to track an LZ4 stream.
+ init this structure before first use.
+ note : only use in association with static linking !
+        this definition is not API/ABI safe,
+        and may change in a future version !
+ 
+</p></pre><BR>
+
+<pre><b>#define LZ4_STREAMDECODESIZE_U64  4
+#define LZ4_STREAMDECODESIZE     (LZ4_STREAMDECODESIZE_U64 * sizeof(unsigned long long))
+union LZ4_streamDecode_u {
+    unsigned long long table[LZ4_STREAMDECODESIZE_U64];
+    LZ4_streamDecode_t_internal internal_donotuse;
+} ;   </b>/* previously typedef'd to LZ4_streamDecode_t */<b>
+</b><p> information structure to track an LZ4 stream during decompression.
+ init this structure  using LZ4_setStreamDecode (or memset()) before first use
+ note : only use in association with static linking !
+        this definition is not API/ABI safe,
+        and may change in a future version !
+ 
+</p></pre><BR>
+
+<a name="Chapter9"></a><h2>Obsolete Functions</h2><pre></pre>
+
+<pre><b>#ifdef LZ4_DISABLE_DEPRECATE_WARNINGS
+#  define LZ4_DEPRECATED(message)   </b>/* disable deprecation warnings */<b>
+#else
+#  define LZ4_GCC_VERSION (__GNUC__ * 100 + __GNUC_MINOR__)
+#  if defined (__cplusplus) && (__cplusplus >= 201402) </b>/* C++14 or greater */<b>
+#    define LZ4_DEPRECATED(message) [[deprecated(message)]]
+#  elif (LZ4_GCC_VERSION >= 405) || defined(__clang__)
+#    define LZ4_DEPRECATED(message) __attribute__((deprecated(message)))
+#  elif (LZ4_GCC_VERSION >= 301)
+#    define LZ4_DEPRECATED(message) __attribute__((deprecated))
+#  elif defined(_MSC_VER)
+#    define LZ4_DEPRECATED(message) __declspec(deprecated(message))
+#  else
+#    pragma message("WARNING: You need to implement LZ4_DEPRECATED for this compiler")
+#    define LZ4_DEPRECATED(message)
+#  endif
+#endif </b>/* LZ4_DISABLE_DEPRECATE_WARNINGS */<b>
+</b><p>   Should deprecation warnings be a problem,
+   it is generally possible to disable them,
+   typically with -Wno-deprecated-declarations for gcc
+   or _CRT_SECURE_NO_WARNINGS in Visual.
+   Otherwise, it's also possible to define LZ4_DISABLE_DEPRECATE_WARNINGS 
 </p></pre><BR>
 
 </html>
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html
new file mode 100644
index 0000000..f76ec3d
--- /dev/null
+++ b/doc/lz4frame_manual.html
@@ -0,0 +1,240 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>lz4frame 1.7.5 Manual</title>
+</head>
+<body>
+<h1>lz4frame 1.7.5 Manual</h1>
+<hr>
+<a name="Contents"></a><h2>Contents</h2>
+<ol>
+<li><a href="#Chapter1">Introduction</a></li>
+<li><a href="#Chapter2">Error management</a></li>
+<li><a href="#Chapter3">Frame compression types</a></li>
+<li><a href="#Chapter4">Simple compression function</a></li>
+<li><a href="#Chapter5">Advanced compression functions</a></li>
+<li><a href="#Chapter6">Decompression functions</a></li>
+</ol>
+<hr>
+<a name="Chapter1"></a><h2>Introduction</h2><pre>
+  lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md).
+  lz4frame.h provides frame compression functions that take care
+  of encoding standard metadata alongside LZ4-compressed blocks.
+<BR></pre>
+
+<a name="Chapter2"></a><h2>Error management</h2><pre></pre>
+
+<pre><b>unsigned    LZ4F_isError(LZ4F_errorCode_t code);   </b>/**< tells if a `LZ4F_errorCode_t` function result is an error code */<b>
+</b></pre><BR>
+<pre><b>const char* LZ4F_getErrorName(LZ4F_errorCode_t code);   </b>/**< return error code string; useful for debugging */<b>
+</b></pre><BR>
+<a name="Chapter3"></a><h2>Frame compression types</h2><pre></pre>
+
+<pre><b>typedef enum {
+    LZ4F_default=0,
+    LZ4F_max64KB=4,
+    LZ4F_max256KB=5,
+    LZ4F_max1MB=6,
+    LZ4F_max4MB=7
+    LZ4F_OBSOLETE_ENUM(max64KB)
+    LZ4F_OBSOLETE_ENUM(max256KB)
+    LZ4F_OBSOLETE_ENUM(max1MB)
+    LZ4F_OBSOLETE_ENUM(max4MB)
+} LZ4F_blockSizeID_t;
+</b></pre><BR>
+<pre><b>typedef enum {
+    LZ4F_blockLinked=0,
+    LZ4F_blockIndependent
+    LZ4F_OBSOLETE_ENUM(blockLinked)
+    LZ4F_OBSOLETE_ENUM(blockIndependent)
+} LZ4F_blockMode_t;
+</b></pre><BR>
+<pre><b>typedef enum {
+    LZ4F_noContentChecksum=0,
+    LZ4F_contentChecksumEnabled
+    LZ4F_OBSOLETE_ENUM(noContentChecksum)
+    LZ4F_OBSOLETE_ENUM(contentChecksumEnabled)
+} LZ4F_contentChecksum_t;
+</b></pre><BR>
+<pre><b>typedef enum {
+    LZ4F_frame=0,
+    LZ4F_skippableFrame
+    LZ4F_OBSOLETE_ENUM(skippableFrame)
+} LZ4F_frameType_t;
+</b></pre><BR>
+<pre><b>typedef struct {
+  LZ4F_blockSizeID_t     blockSizeID;           </b>/* max64KB, max256KB, max1MB, max4MB ; 0 == default */<b>
+  LZ4F_blockMode_t       blockMode;             </b>/* blockLinked, blockIndependent ; 0 == default */<b>
+  LZ4F_contentChecksum_t contentChecksumFlag;   </b>/* noContentChecksum, contentChecksumEnabled ; 0 == default  */<b>
+  LZ4F_frameType_t       frameType;             </b>/* LZ4F_frame, skippableFrame ; 0 == default */<b>
+  unsigned long long     contentSize;           </b>/* Size of uncompressed (original) content ; 0 == unknown */<b>
+  unsigned               reserved[2];           </b>/* must be zero for forward compatibility */<b>
+} LZ4F_frameInfo_t;
+</b><p> makes it possible to supply detailed frame parameters to the stream interface.
+ It's not required to set all fields, as long as the structure was initially memset() to zero.
+ All reserved fields must be set to zero. 
+</p></pre><BR>
+
+<pre><b>typedef struct {
+  LZ4F_frameInfo_t frameInfo;
+  int      compressionLevel;       </b>/* 0 == default (fast mode); values above 16 count as 16; values below 0 count as 0 */<b>
+  unsigned autoFlush;              </b>/* 1 == always flush (reduce usage of tmp buffer) */<b>
+  unsigned reserved[4];            </b>/* must be zero for forward compatibility */<b>
+} LZ4F_preferences_t;
+</b><p> makes it possible to supply detailed compression parameters to the stream interface.
+ It's not required to set all fields, as long as the structure was initially memset() to zero.
+ All reserved fields must be set to zero. 
+</p></pre><BR>
+
+<a name="Chapter4"></a><h2>Simple compression function</h2><pre></pre>
+
+<pre><b>size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
+</b><p> Returns the maximum possible size of a frame compressed with LZ4F_compressFrame() given srcSize content and preferences.
+ Note : this result is only usable with LZ4F_compressFrame(), not with multi-segments compression.
+ 
+</p></pre><BR>
+
+<pre><b>size_t LZ4F_compressFrame(void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_preferences_t* preferencesPtr);
+</b><p> Compress an entire srcBuffer into a valid LZ4 frame, as defined by specification v1.5.1
+ 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.
+ @return : number of bytes written into dstBuffer.
+           or an error code if it fails (can be tested using LZ4F_isError())
+ 
+</p></pre><BR>
+
+<a name="Chapter5"></a><h2>Advanced compression functions</h2><pre></pre>
+
+<pre><b>typedef struct {
+  unsigned stableSrc;    </b>/* 1 == src content will remain present on future calls to LZ4F_compress(); skip copying src content within tmp buffer */<b>
+  unsigned reserved[3];
+} LZ4F_compressOptions_t;
+</b></pre><BR>
+<pre><b>LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
+LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
+</b><p> 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 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();
+ 
+</p></pre><BR>
+
+<pre><b>size_t LZ4F_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr);
+</b><p> will write the frame header into dstBuffer.
+ dstCapacity must be large enough to store the header. Maximum header size is LZ4F_HEADER_SIZE_MAX 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())
+ 
+</p></pre><BR>
+
+<pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
+</b><p> Provides dstCapacity given a srcSize to guarantee operation success in worst case situations.
+ prefsPtr is optional : you can provide NULL as argument, preferences will be set to cover worst case scenario.
+ Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers.
+ When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations.
+ 
+</p></pre><BR>
+
+<pre><b>size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* cOptPtr);
+</b><p> LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary.
+ An important rule is that dstCapacity MUST be large enough to ensure operation success even in worst case situations.
+ This value is provided by LZ4F_compressBound().
+ If this condition is not respected, LZ4F_compress() will fail (result is an errorCode).
+ LZ4F_compressUpdate() doesn't guarantee error recovery. When an error occurs, compression context must be freed or resized.
+ `cOptPtr` is optional : NULL can be provided, in which case all options are 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())
+ 
+</p></pre><BR>
+
+<pre><b>size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);
+</b><p> 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())
+ 
+</p></pre><BR>
+
+<pre><b>size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);
+</b><p> To properly finish an LZ4 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 : NULL can be provided, in which case 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.
+ 
+</p></pre><BR>
+
+<a name="Chapter6"></a><h2>Decompression functions</h2><pre></pre>
+
+<pre><b>typedef struct {
+  unsigned stableDst;       </b>/* guarantee that decompressed data will still be there on next function calls (avoid storage into tmp buffers) */<b>
+  unsigned reserved[3];
+} LZ4F_decompressOptions_t;
+</b></pre><BR>
+<pre><b>LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr, unsigned version);
+LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx);
+</b><p> Create an LZ4F_decompressionContext_t object, which will be used to track all decompression operations.
+ The version provided MUST be LZ4F_VERSION. It is intended to track potential breaking differences between different versions.
+ The function will provide a pointer to a fully allocated and initialized LZ4F_decompressionContext_t object.
+ The result is an errorCode, which can be tested using LZ4F_isError().
+ dctx memory can be released using LZ4F_freeDecompressionContext();
+ The result of LZ4F_freeDecompressionContext() is indicative of the current state of decompressionContext when being released.
+ That is, it should be == 0 if decompression has been completed fully and correctly.
+ 
+</p></pre><BR>
+
+<pre><b>size_t LZ4F_getFrameInfo(LZ4F_dctx* dctx,
+                                     LZ4F_frameInfo_t* frameInfoPtr,
+                                     const void* srcBuffer, size_t* srcSizePtr);
+</b><p> This function decodes frame header information (such as max blockSize, frame checksum, etc.).
+ Its usage is optional. The objective is to extract frame header information, typically for allocation purposes.
+ A header size is variable and can length from 7 to 15 bytes. It's possible to provide more input bytes than that.
+ The number of bytes consumed from srcBuffer will be updated within *srcSizePtr (necessarily <= original value).
+ Decompression must resume from this point (srcBuffer + *srcSizePtr).
+ Note that LZ4F_getFrameInfo() can also be used anytime *after* decompression is started, in which case 0 input byte can be enough.
+ Frame header info is *copied into* an already allocated LZ4F_frameInfo_t structure.
+ @return : an hint about how many srcSize bytes LZ4F_decompress() expects for next call,
+           or an error code which can be tested using LZ4F_isError()
+           (typically, when there is not enough src bytes to fully decode the frame header)
+ 
+</p></pre><BR>
+
+<pre><b>size_t LZ4F_decompress(LZ4F_dctx* dctx,
+                                   void* dstBuffer, size_t* dstSizePtr,
+                                   const void* srcBuffer, size_t* srcSizePtr,
+                                   const LZ4F_decompressOptions_t* dOptPtr);
+</b><p> Call this function repetitively to regenerate data compressed within `srcBuffer`.
+ The function will attempt to decode up to *srcSizePtr bytes from srcBuffer, into dstBuffer of capacity *dstSizePtr.
+
+ The number of bytes regenerated into dstBuffer will be provided within *dstSizePtr (necessarily <= original value).
+
+ The number of bytes read from srcBuffer will be provided within *srcSizePtr (necessarily <= original value).
+ Number of bytes read can be < number of bytes provided, meaning there is some more data to decode.
+ It typically happens when dstBuffer is not large enough to contain all decoded data.
+ Remaining data will have to be presented again in a subsequent invocation.
+
+ `dstBuffer` content is expected to be flushed between each invocation, as its content will be overwritten.
+ `dstBuffer` can be changed at will between each consecutive function invocation.
+
+ @return is an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call.
+ Schematically, it's the size of the current (or remaining) compressed block + header of next block.
+ Respecting the hint provides some boost to performance, since it does skip intermediate buffers.
+ This is just a hint though, it's always possible to provide any srcSize.
+ When a frame is fully decoded, @return will be 0 (no more data expected).
+ If decompression failed, @return is an error code, which can be tested using LZ4F_isError().
+
+ After a frame is fully decoded, dctx can be used again to decompress another frame.
+ 
+</p></pre><BR>
+
+</html>
+</body>
diff --git a/lib/Makefile b/lib/Makefile
index 2d9c8f3..7ba9ccb 100644
--- a/lib/Makefile
+++ b/lib/Makefile
@@ -3,6 +3,8 @@
 # Copyright (C) Yann Collet 2011-2016
 # All rights reserved.
 #
+# This Makefile is validated for Linux, macOS, *BSD, Hurd, Solaris, MSYS2 targets
+#
 # BSD license
 # Redistribution and use in source and binary forms, with or without modification,
 # are permitted provided that the following conditions are met:
diff --git a/lib/lz4.h b/lib/lz4.h
index 3dc115b..bebe761 100644
--- a/lib/lz4.h
+++ b/lib/lz4.h
@@ -82,7 +82,7 @@ extern "C" {
 #endif
 
 
-/*========== Version =========== */
+/*------   Version   ------*/
 #define LZ4_VERSION_MAJOR    1    /* for breaking interface changes  */
 #define LZ4_VERSION_MINOR    7    /* for new (non-breaking) interface capabilities */
 #define LZ4_VERSION_RELEASE  5    /* for tweaks, bug-fixes, or development */
@@ -94,8 +94,8 @@ extern "C" {
 #define LZ4_EXPAND_AND_QUOTE(str) LZ4_QUOTE(str)
 #define LZ4_VERSION_STRING LZ4_EXPAND_AND_QUOTE(LZ4_LIB_VERSION)
 
-LZ4LIB_API int LZ4_versionNumber (void);
-LZ4LIB_API const char* LZ4_versionString (void);
+LZ4LIB_API int LZ4_versionNumber (void);  /**< library version number; to be used when checking dll version */
+LZ4LIB_API const char* LZ4_versionString (void);   /**< library version string; to be used when checking dll version */
 
 
 /*-************************************
@@ -275,7 +275,8 @@ LZ4LIB_API int LZ4_saveDict (LZ4_stream_t* streamPtr, char* safeBuffer, int dict
 ************************************************/
 typedef union LZ4_streamDecode_u LZ4_streamDecode_t;   /* incomplete type (defined later) */
 
-/* creation / destruction of streaming decompression tracking structure */
+/*! LZ4_createStreamDecode() and LZ4_freeStreamDecode() :
+ *  creation / destruction of streaming decompression tracking structure */
 LZ4LIB_API LZ4_streamDecode_t* LZ4_createStreamDecode(void);
 LZ4LIB_API int                 LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
 
@@ -401,11 +402,12 @@ union LZ4_streamDecode_u {
 } ;   /* previously typedef'd to LZ4_streamDecode_t */
 
 
-/*=************************************
+/*-************************************
 *  Obsolete Functions
 **************************************/
-/* Deprecation warnings */
-/* Should these warnings be a problem,
+
+/*! Deprecation warnings
+   Should deprecation warnings be a problem,
    it is generally possible to disable them,
    typically with -Wno-deprecated-declarations for gcc
    or _CRT_SECURE_NO_WARNINGS in Visual.
diff --git a/lib/lz4frame.h b/lib/lz4frame.h
index a4a4ce6..82fbeab 100644
--- a/lib/lz4frame.h
+++ b/lib/lz4frame.h
@@ -48,10 +48,19 @@ extern "C" {
 /* ---   Dependency   --- */
 #include <stddef.h>   /* size_t */
 
-/*-***************************************************************
+
+/**
+  Introduction
+
+  lz4frame.h implements LZ4 frame specification (doc/lz4_Frame_format.md).
+  lz4frame.h provides frame compression functions that take care
+  of encoding standard metadata alongside LZ4-compressed blocks.
+*/
+
+/*^***************************************************************
 *  Compiler specifics
 *****************************************************************/
-/*!
+/*
 *  LZ4_DLL_EXPORT :
 *  Enable exporting of functions when building a Windows DLL
 */
@@ -77,8 +86,8 @@ extern "C" {
 **************************************/
 typedef size_t LZ4F_errorCode_t;
 
-LZ4FLIB_API unsigned    LZ4F_isError(LZ4F_errorCode_t code);
-LZ4FLIB_API const char* LZ4F_getErrorName(LZ4F_errorCode_t code);   /* return error code string; useful for debugging */
+LZ4FLIB_API unsigned    LZ4F_isError(LZ4F_errorCode_t code);   /**< tells if a `LZ4F_errorCode_t` function result is an error code */
+LZ4FLIB_API const char* LZ4F_getErrorName(LZ4F_errorCode_t code);   /**< return error code string; useful for debugging */
 
 
 /*-************************************
@@ -130,7 +139,7 @@ typedef LZ4F_frameType_t frameType_t;
 typedef LZ4F_contentChecksum_t contentChecksum_t;
 #endif
 
-/* LZ4F_frameInfo_t :
+/*! LZ4F_frameInfo_t :
  * makes it possible to supply detailed frame parameters to the stream interface.
  * It's not required to set all fields, as long as the structure was initially memset() to zero.
  * All reserved fields must be set to zero. */
@@ -143,7 +152,7 @@ typedef struct {
   unsigned               reserved[2];           /* must be zero for forward compatibility */
 } LZ4F_frameInfo_t;
 
-/* LZ4F_preferences_t :
+/*! LZ4F_preferences_t :
  * makes it possible to supply detailed compression parameters to the stream interface.
  * It's not required to set all fields, as long as the structure was initially memset() to zero.
  * All reserved fields must be set to zero. */
@@ -192,9 +201,7 @@ typedef struct {
 
 #define LZ4F_VERSION 100
 LZ4FLIB_API unsigned LZ4F_getVersion(void);
-LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
-LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
-/* LZ4F_createCompressionContext() :
+/*! 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 mismatch, notably when using DLL.
@@ -202,30 +209,31 @@ LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
  * If @return != zero, there was an error during context creation.
  * Object can release its memory using LZ4F_freeCompressionContext();
  */
+LZ4FLIB_API LZ4F_errorCode_t LZ4F_createCompressionContext(LZ4F_cctx** cctxPtr, unsigned version);
+LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
 
 
 /* Compression */
 
 #define LZ4F_HEADER_SIZE_MAX 15
-LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr);
-/* LZ4F_compressBegin() :
+/*! LZ4F_compressBegin() :
  * will write the frame header into dstBuffer.
  * dstCapacity must be large enough to store the header. Maximum header size is LZ4F_HEADER_SIZE_MAX 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_compressBegin(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_preferences_t* prefsPtr);
 
-LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
-/* LZ4F_compressBound() :
+/*! LZ4F_compressBound() :
  * Provides dstCapacity given a srcSize to guarantee operation success in worst case situations.
  * prefsPtr is optional : you can provide NULL as argument, preferences will be set to cover worst case scenario.
  * Result is always the same for a srcSize and prefsPtr, so it can be trusted to size reusable buffers.
  * When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() operations.
  */
+LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
 
-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() :
  * LZ4F_compressUpdate() can be called repetitively to compress as much data as necessary.
  * An important rule is that dstCapacity MUST be large enough to ensure operation success even in worst case situations.
  * This value is provided by LZ4F_compressBound().
@@ -235,9 +243,9 @@ LZ4FLIB_API size_t LZ4F_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t
  * @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_compressUpdate(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const void* srcBuffer, size_t srcSize, const LZ4F_compressOptions_t* cOptPtr);
 
-LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);
-/* LZ4F_flush() :
+/*! 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.
@@ -245,9 +253,9 @@ LZ4FLIB_API size_t LZ4F_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapaci
  * @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_flush(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);
 
-LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);
-/* LZ4F_compressEnd() :
+/*! LZ4F_compressEnd() :
  * To properly finish an LZ4 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.
@@ -256,6 +264,7 @@ LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dst
  *           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.
  */
+LZ4FLIB_API size_t LZ4F_compressEnd(LZ4F_cctx* cctx, void* dstBuffer, size_t dstCapacity, const LZ4F_compressOptions_t* cOptPtr);
 
 
 /*-*********************************
@@ -285,7 +294,7 @@ LZ4FLIB_API LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_dctx** dctxPtr
 LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_dctx* const dctx);
 
 
-/*======   Decompression   ======*/
+/* ======   Decompression   ======*/
 
 /*!LZ4F_getFrameInfo() :
  * This function decodes frame header information (such as max blockSize, frame checksum, etc.).
diff --git a/programs/Makefile b/programs/Makefile
index 060ce21..8a271c2 100644
--- a/programs/Makefile
+++ b/programs/Makefile
@@ -2,6 +2,8 @@
 # LZ4 programs - Makefile
 # Copyright (C) Yann Collet 2011-2016
 #
+# This Makefile is validated for Linux, macOS, *BSD, Hurd, Solaris, MSYS2 targets
+#
 # GPL v2 License
 #
 # This program is free software; you can redistribute it and/or modify
diff --git a/tests/Makefile b/tests/Makefile
index 97fa782..5f8efb7 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -2,6 +2,8 @@
 # LZ4 programs - Makefile
 # Copyright (C) Yann Collet 2011-2016
 #
+# This Makefile is validated for Linux, macOS, *BSD, Hurd, Solaris, MSYS2 targets
+#
 # GPL v2 License
 #
 # This program is free software; you can redistribute it and/or modify