updated API documentation

1 files changed, 20 insertions, 6 deletions

diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html
index e079db2..e5044fe 100644
--- a/doc/lz4_manual.html
+++ b/doc/lz4_manual.html
@@ -278,7 +278,16 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize,
 <BR></pre>
 
 <pre><b>void LZ4_resetStream_fast (LZ4_stream_t* streamPtr);
-</b><p>  When an LZ4_stream_t is known to be in a internally coherent state,
+</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()).
+
+  Note:
+  Using this in advance of a non- streaming-compression function is redundant,
+  and potentially bad for performance, 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
@@ -287,13 +296,17 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize,
   LZ4_streams are guaranteed to be in a valid state when:
   - returned from LZ4_createStream()
   - reset by LZ4_resetStream()
-  - memset(stream, 0, sizeof(LZ4_stream_t))
+  - memset(stream, 0, sizeof(LZ4_stream_t)), though this is discouraged
   - the stream was in a valid state and was reset by LZ4_resetStream_fast()
   - the stream was in a valid state and was then used in any compression call
     that returned success
   - the stream was in an indeterminate state and was used in a compression
-    call that fully reset the state (LZ4_compress_fast_extState()) and that
-    returned success
+    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().
  
 </p></pre><BR>
 
@@ -304,8 +317,9 @@ int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize,
   to call if the state buffer is known to be correctly initialized already
   (see above comment on LZ4_resetStream_fast() for a definition of "correctly
   initialized"). From a high level, the difference is that this function
-  initializes the provided state with a call to LZ4_resetStream_fast() while
-  LZ4_compress_fast_extState() starts with a call to LZ4_resetStream().
+  initializes the provided state with a call to something like
+  LZ4_resetStream_fast() while LZ4_compress_fast_extState() starts with a
+  call to LZ4_resetStream().
  
 </p></pre><BR>