updated code documentation

to clarify #589

1 files changed, 14 insertions, 8 deletions

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>