clarified documentation of streaming decompression functions

(synchronous bufferless mode)
answering questions by @jtbandes (#394)

1 files changed, 13 insertions, 9 deletions

diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html
index df8128b..e3f6681 100644
--- a/doc/lz4_manual.html
+++ b/doc/lz4_manual.html
@@ -193,32 +193,36 @@ int           LZ4_freeStream (LZ4_stream_t* streamPtr);
 
 <pre><b>LZ4_streamDecode_t* LZ4_createStreamDecode(void);
 int                 LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
-</b><p>  creation / destruction of streaming decompression tracking structure 
+</b><p>  creation / destruction of streaming decompression tracking structure.
+  A tracking structure can be re-used multiple times sequentially. 
 </p></pre><BR>
 
 <pre><b>int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize);
-</b><p>  Use this function to instruct where to find the dictionary.
-  Setting a size of 0 is allowed (same effect as reset).
-  @return : 1 if OK, 0 if error
+</b><p>  Use this function to start decompression of a new stream of blocks.
+  A dictionary can optionnally be set. Use NULL or size 0 for a simple reset order.
+ @return : 1 if OK, 0 if error
  
 </p></pre><BR>
 
 <pre><b>int LZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* source, char* dest, int compressedSize, int maxDecompressedSize);
 int LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* source, char* dest, int originalSize);
-</b><p>  These decoding functions allow decompression of multiple blocks in "streaming" mode.
-  Previously decoded blocks *must* remain available at the memory position where they were decoded (up to 64 KB)
-  In the case of a ring buffers, decoding buffer must be either :
+</b><p>  These decoding functions allow decompression of consecutive blocks in "streaming" mode.
+  A block is an unsplittable entity, it must be presented entirely to a decompression function.
+  Decompression functions only accept one block at a time.
+  Previously decoded blocks *must* remain available at the memory position where they were decoded (up to 64 KB).
+
+  Special : if application sets a ring buffer for decompression, it must respect one of the following conditions :
   - Exactly same size as encoding buffer, with same update rule (block boundaries at same positions)
     In which case, the decoding & encoding ring buffer can have any size, including very small ones ( < 64 KB).
   - Larger than encoding buffer, by a minimum of maxBlockSize more bytes.
-    maxBlockSize is implementation dependent. It's the maximum size you intend to compress into a single block.
+    maxBlockSize is implementation dependent. It's the maximum size of any single block.
     In which case, encoding and decoding buffers do not need to be synchronized,
     and encoding ring buffer can have any size, including small ones ( < 64 KB).
   - _At least_ 64 KB + 8 bytes + maxBlockSize.
     In which case, encoding and decoding buffers do not need to be synchronized,
     and encoding ring buffer can have any size, including larger than decoding buffer.
   Whenever these conditions are not possible, save the last 64KB of decoded data into a safe buffer,
-  and indicate where it is saved using LZ4_setStreamDecode()
+  and indicate where it is saved using LZ4_setStreamDecode() before decompressin next block.
 </p></pre><BR>
 
 <pre><b>int LZ4_decompress_safe_usingDict (const char* source, char* dest, int compressedSize, int maxDecompressedSize, const char* dictStart, int dictSize);