updated code documentation

to clarify #589

3 files changed, 42 insertions, 26 deletions

diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html
index 5e04263..4c4734a 100644
--- a/doc/lz4_manual.html
+++ b/doc/lz4_manual.html
@@ -304,19 +304,22 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize,
 <BR></pre>
 
 <pre><b>LZ4LIB_STATIC_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr);
-</b><p>  Use this, like LZ4_resetStream(), to prepare a context for a new chain of
-  calls to a streaming API (e.g., LZ4_compress_fast_continue()).
+</b><p>  Use this to prepare a context for a new chain of calls to a streaming API
+  (e.g., LZ4_compress_fast_continue()).
+
+  Note:
+  To stay on the safe side, when LZ4_stream_t is used for the first time,
+  it should be either created using LZ4_createStream() or
+  initialized using LZ4_resetStream().
 
   Note:
   Using this in advance of a non-streaming-compression function is redundant,
   since they all perform their own custom reset internally.
 
   Differences from LZ4_resetStream():
-  When an LZ4_stream_t is known to be in a internally coherent state,
-  it can often be prepared for a new compression with almost no work,
-  only sometimes falling back to the full, expensive reset
-  that is always required when the stream is in an indeterminate state
-  (i.e., the reset performed by LZ4_resetStream()).
+  When an LZ4_stream_t is known to be in an internally coherent state,
+  it will be prepared for a new compression with almost no work.
+  Otherwise, it will fall back to the full, expensive reset.
 
   LZ4_streams are guaranteed to be in a valid state when:
   - returned from LZ4_createStream()
@@ -329,9 +332,11 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize,
     call that fully reset the state (e.g., LZ4_compress_fast_extState()) and
     that returned success
 
-  When a stream isn't known to be in a valid state, it is not safe to pass to
-  any fastReset or streaming function. It must first be cleansed by the full
-  LZ4_resetStream().
+  Note:
+  A stream that was used in a compression call that did not return success
+  (e.g., LZ4_compress_fast_continue()), can still be passed to this function,
+  however, it's history is not preserved because of previous compression
+  failure.
  
 </p></pre><BR>
 
diff --git a/doc/lz4frame_manual.html b/doc/lz4frame_manual.html
index 72e6782..2b16045 100644
--- a/doc/lz4frame_manual.html
+++ b/doc/lz4frame_manual.html
@@ -157,15 +157,19 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
 </p></pre><BR>
 
 <pre><b>size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);
-</b><p>  Provides minimum dstCapacity required to guarantee compression success
-  given a srcSize and preferences, covering worst case scenario.
+</b><p>  Provides minimum dstCapacity required to guarantee success of
+  LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario.
+  When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead.
+  Note that the result is only valid for a single invocation of LZ4F_compressUpdate().
+  When invoking LZ4F_compressUpdate() multiple times,
+  if the output buffer is gradually filled up instead of emptied and re-used from its start,
+  one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound().
+ @return is always the same for a srcSize and prefsPtr.
   prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario.
-  Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(),
-  Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
-  It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd().
-  Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin().
-  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.
+  tech details :
+ @return includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
+  It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd().
+ @return doesn't include frame header, as it was already generated by LZ4F_compressBegin().
  
 </p></pre><BR>
 
@@ -194,6 +198,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
  `cOptPtr` is optional : it's possible to provide NULL, all options will be set to default.
  @return : nb of bytes written into dstBuffer (can be zero, when there is no data stored within cctx)
            or an error code if it fails (which can be tested using LZ4F_isError())
+  Note : LZ4F_flush() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr).
  
 </p></pre><BR>
 
@@ -206,6 +211,7 @@ LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
  `cOptPtr` is optional : NULL can be provided, in which case all options will be set to default.
  @return : nb of bytes written into dstBuffer, necessarily >= 4 (endMark),
            or an error code if it fails (which can be tested using LZ4F_isError())
+  Note : LZ4F_compressEnd() is guaranteed to be successful when dstCapacity >= LZ4F_compressBound(0, prefsPtr).
   A successful call to LZ4F_compressEnd() makes `cctx` available again for another compression task.
  
 </p></pre><BR>
diff --git a/lib/lz4frame.h b/lib/lz4frame.h
index 599f17e..7c7c34e 100644
--- a/lib/lz4frame.h
+++ b/lib/lz4frame.h
@@ -248,6 +248,7 @@ LZ4FLIB_API LZ4F_errorCode_t LZ4F_freeCompressionContext(LZ4F_cctx* cctx);
 /*----    Compression    ----*/
 
 #define LZ4F_HEADER_SIZE_MAX 19   /* LZ4 Frame header size can vary from 7 to 19 bytes */
+
 /*! LZ4F_compressBegin() :
  *  will write the frame header into dstBuffer.
  *  dstCapacity must be >= LZ4F_HEADER_SIZE_MAX bytes.
@@ -260,15 +261,19 @@ LZ4FLIB_API size_t LZ4F_compressBegin(LZ4F_cctx* cctx,
                                       const LZ4F_preferences_t* prefsPtr);
 
 /*! LZ4F_compressBound() :
- *  Provides minimum dstCapacity required to guarantee compression success
- *  given a srcSize and preferences, covering worst case scenario.
+ *  Provides minimum dstCapacity required to guarantee success of
+ *  LZ4F_compressUpdate(), given a srcSize and preferences, for a worst case scenario.
+ *  When srcSize==0, LZ4F_compressBound() provides an upper bound for LZ4F_flush() and LZ4F_compressEnd() instead.
+ *  Note that the result is only valid for a single invocation of LZ4F_compressUpdate().
+ *  When invoking LZ4F_compressUpdate() multiple times,
+ *  if the output buffer is gradually filled up instead of emptied and re-used from its start,
+ *  one must check if there is enough remaining capacity before each invocation, using LZ4F_compressBound().
+ * @return is always the same for a srcSize and prefsPtr.
  *  prefsPtr is optional : when NULL is provided, preferences will be set to cover worst case scenario.
- *  Estimation is valid for either LZ4F_compressUpdate(), LZ4F_flush() or LZ4F_compressEnd(),
- *  Estimation includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
- *  It also includes frame footer (ending + checksum), which would have to be generated by LZ4F_compressEnd().
- *  Estimation doesn't include frame header, as it was already generated by LZ4F_compressBegin().
- *  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.
+ *  tech details :
+ * @return includes the possibility that internal buffer might already be filled by up to (blockSize-1) bytes.
+ *  It also includes frame footer (ending + checksum), since it might be generated by LZ4F_compressEnd().
+ * @return doesn't include frame header, as it was already generated by LZ4F_compressBegin().
  */
 LZ4FLIB_API size_t LZ4F_compressBound(size_t srcSize, const LZ4F_preferences_t* prefsPtr);