updated doc to underline difference between block and frame

as this is a very frequent source of confusion for new users.

3 files changed, 24 insertions, 16 deletions

diff --git a/lib/README.md b/lib/README.md
index c6daaea..b753195 100644
--- a/lib/README.md
+++ b/lib/README.md
@@ -16,13 +16,14 @@ They generate and decode data using the [LZ4 block format].
 For more compression ratio at the cost of compression speed,
 the High Compression variant called **lz4hc** is available.
 Add files **`lz4hc.c`** and **`lz4hc.h`**.
-This variant also depends on regular `lib/lz4.*` source files.
+This variant also compresses data using the [LZ4 block format],
+and depends on regular `lib/lz4.*` source files.
 
 
 #### Frame support, for interoperability
 
 In order to produce compressed data compatible with `lz4` command line utility,
-it's necessary to encode lz4-compressed blocks using the [official interoperable frame format].
+it's necessary to use the [official interoperable frame format].
 This format is generated and decoded automatically by the **lz4frame** library.
 Its public API is described in `lib/lz4frame.h`.
 In order to work properly, lz4frame needs all other modules present in `/lib`,
@@ -44,7 +45,7 @@ by using build macro `LZ4_PUBLISH_STATIC_FUNCTIONS`.
 
 #### Build macros
 
-The following build macro can be determined at compilation time :
+The following build macro can be selected at compilation time :
 
 - `LZ4_FAST_DEC_LOOP` : this triggers the optimized decompression loop.
   This loops works great on x86/x64 cpus, and is automatically enabled on this platform.
@@ -61,7 +62,7 @@ The following build macro can be determined at compilation time :
 
 - `LZ4_DISABLE_DEPRECATE_WARNINGS` : invoking a deprecated function will make the compiler generate a warning.
   This is meant to invite users to update their source code.
-  Should this be a problem, it's generally to make the compiler ignore these warnings,
+  Should this be a problem, it's generally possible to make the compiler ignore these warnings,
   for example with `-Wno-deprecated-declarations` on `gcc`,
   or `_CRT_SECURE_NO_WARNINGS` for Visual Studio.
   Another method is to define `LZ4_DISABLE_DEPRECATE_WARNINGS`
diff --git a/lib/lz4.h b/lib/lz4.h
index 935b55f..23b5ac5 100644
--- a/lib/lz4.h
+++ b/lib/lz4.h
@@ -51,19 +51,23 @@ extern "C" {
   multiple GB/s per core, typically reaching RAM speed limits on multi-core systems.
 
   The LZ4 compression library provides in-memory compression and decompression functions.
+  It gives full buffer control to user.
   Compression can be done in:
     - a single step (described as Simple Functions)
     - a single step, reusing a context (described in Advanced Functions)
     - unbounded multiple steps (described as Streaming compression)
 
-  lz4.h provides block compression functions. It gives full buffer control to user.
-  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.
+  lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md).
+  Decompressing a block requires additional metadata, such as its compressed size.
+  Each application is free to encode and pass 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.
-  Frame format is required for interoperability.
-  It is delivered through a companion API, declared in lz4frame.h.
+  lz4.h only handle blocks, it can not generate Frames.
+
+  Blocks are different from Frames (doc/lz4_Frame_format.md).
+  Frames bundle both blocks and metadata in a specified manner.
+  This are required for compressed data to be self-contained and portable.
+  Frame format is delivered through a companion API, declared in lz4frame.h.
+  Note that the `lz4` CLI can only manage frames.
 */
 
 /*^***************************************************************
diff --git a/lib/lz4frame.h b/lib/lz4frame.h
index 5c68628..ca20dc9 100644
--- a/lib/lz4frame.h
+++ b/lib/lz4frame.h
@@ -32,11 +32,14 @@
    - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c
 */
 
-/* LZ4F is a stand-alone API to create LZ4-compressed frames
- * conformant with specification v1.6.1.
- * It also offers streaming capabilities.
+/* LZ4F is a stand-alone API able to create and decode LZ4 frames
+ * conformant with specification v1.6.1 in doc/lz4_Frame_format.md .
+ * Generated frames are compatible with `lz4` CLI.
+ *
+ * LZ4F also offers streaming capabilities.
+ *
  * lz4.h is not required when using lz4frame.h,
- * except to get constant such as LZ4_VERSION_NUMBER.
+ * except to extract common constant such as LZ4_VERSION_NUMBER.
  * */
 
 #ifndef LZ4F_H_09782039843
@@ -195,7 +198,7 @@ typedef struct {
 *  Simple compression function
 ***********************************/
 
-LZ4FLIB_API int LZ4F_compressionLevel_max(void);
+LZ4FLIB_API int LZ4F_compressionLevel_max(void);   /* v1.8.0+ */
 
 /*! LZ4F_compressFrameBound() :
  *  Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences.