Comments

5 files changed, 65 insertions, 39 deletions

diff --git a/src/liblzma/api/lzma/base.h b/src/liblzma/api/lzma/base.h
index e04e7504..ddbcb033 100644
--- a/src/liblzma/api/lzma/base.h
+++ b/src/liblzma/api/lzma/base.h
@@ -243,10 +243,19 @@ typedef enum {
 
 /**
  * \brief       The `action' argument for lzma_code()
+ *
+ * After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or LZMA_FINISH,
+ * the same `action' must is used until lzma_code() returns LZMA_STREAM_END.
+ * Also, the amount of input (that is, strm->avail_in) must not be modified
+ * by the application until lzma_code() returns LZMA_STREAM_END. Changing the
+ * `action' or modifying the amount of input will make lzma_code() return
+ * LZMA_PROG_ERROR.
  */
 typedef enum {
 	LZMA_RUN = 0,
 		/**<
+		 * \brief       Continue coding
+		 *
 		 * Encoder: Encode as much input as possible. Some internal
 		 * buffering will probably be done (depends on the filter
 		 * chain in use), which causes latency: the input used won't
@@ -262,21 +271,37 @@ typedef enum {
 
 	LZMA_SYNC_FLUSH = 1,
 		/**<
-		 * Encoder: Makes all the data given to liblzma via next_in
-		 * available in next_out without resetting the filters. Call
-		 * lzma_code() with LZMA_SYNC_FLUSH until it returns
-		 * LZMA_STREAM_END. Then continue encoding normally.
+		 * \brief       Make all the input available at output
+		 *
+		 * Normally the encoder introduces some latency.
+		 * LZMA_SYNC_FLUSH forces all the buffered data to be
+		 * available at output without resetting the internal
+		 * state of the encoder. This way it is possible to use
+		 * compressed stream for example for communication over
+		 * network.
+		 *
+		 * Only some filters support LZMA_SYNC_FLUSH. Trying to use
+		 * LZMA_SYNC_FLUSH with filters that don't support it will
+		 * make lzma_code() return LZMA_HEADER_ERROR. For example,
+		 * LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does.
 		 *
-		 * \note        Synchronous flushing is supported only by
-		 *              some filters. Using LZMA_SYNC_FLUSH with
-		 *              which such filters will make lzma_code()
-		 *              return LZMA_HEADER_ERROR.
+		 * Using LZMA_SYNC_FLUSH very often can dramatically reduce
+		 * the compression ratio. With some filters (for example,
+		 * LZMA2), finetuning the compression options may help
+		 * mitigate this problem significantly.
 		 *
 		 * Decoders don't support LZMA_SYNC_FLUSH.
 		 */
 
 	LZMA_FULL_FLUSH = 2,
 		/**<
+		 * \brief       Make all the input available at output
+		 *
+		 * This is like LZMA_SYNC_FLUSH except that this resets the
+		 * internal encoder state.
+		 *
+		 *
+		 *
 		 * Finishes encoding of the current Data Block. All the input
 		 * data going to the current Data Block must have been given
 		 * to the encoder (the last bytes can still be pending in
@@ -291,6 +316,11 @@ typedef enum {
 
 	LZMA_FINISH = 3
 		/**<
+		 * \brief       Finish the coding operation
+		 *
+		 *
+		 *
+		 *
 		 * Finishes the coding operation. All the input data must
 		 * have been given to the encoder (the last bytes can still
 		 * be pending in next_in). Call lzma_code() with LZMA_FINISH
@@ -402,35 +432,30 @@ typedef struct lzma_internal_s lzma_internal;
  *   - defining custom memory hander functions; and
  *   - holding a pointer to coder-specific internal data structures.
  *
- * When a new lzma_stream structure is allocated (either as automatic variable
- * on stack or dynamically with malloc()), the new lzma_stream structure must
- * be initialized to LZMA_STREAM_INIT.
+ * The typical usage
  *
- * Before initializing a coder (for example, with lzma_stream_decoder()),
+ *  - After allocating lzma_stream (on stack or with malloc()), it must be
+ *    initialized to LZMA_STREAM_INIT (see LZMA_STREAM_INIT for details).
  *
+ *  - Initialize a coder to the lzma_stream, for example by using
+ *    lzma_easy_encoder() or lzma_auto_decoder(). In contrast to zlib,
+ *    strm->next_in and strm->next_out are ignored by all initialization
+ *    functions, thus it is safe to not initialize them yet. The
+ *    initialization functions always set strm->total_in and strm->total_out
+ *    to zero.
  *
- * Before calling any of the lzma_*_init() functions the first time,
- * the application must reset lzma_stream to LZMA_STREAM_INIT. The
- * lzma_*_init() function will verify the options, allocate internal
- * data structures and store pointer to them into `internal'. Finally
- * total_in and total_out are reset to zero. In contrast to zlib,
- * next_in and avail_in are ignored by the initialization functions.
+ *  - Use lzma_code() to do the actual work.
  *
- * The actual coding is done with the lzma_code() function. Application
- * must update next_in, avail_in, next_out, and avail_out between
- * calls to lzma_decode() just like with zlib.
+ *  - Once the coding has been finished, the existing lzma_stream can be
+ *    reused. It is OK to reuse lzma_stream with different initialization
+ *    function without calling lzma_end() first. Old allocations are
+ *    automatically freed.
  *
- * In contrast to zlib, even the decoder requires that there always
- * is at least one byte space in next_out; if avail_out == 0,
- * LZMA_BUF_ERROR is returned immediatelly. This shouldn't be a problem
- * for most applications that already use zlib, but it's still worth
- * checking your application.
+ *  - Finally, use lzma_end() to free the allocated memory.
  *
  * Application may modify values of total_in and total_out as it wants.
  * They are updated by liblzma to match the amount of data read and
  * written, but liblzma doesn't use the values internally.
- *
- * Application must not touch the `internal' pointer.
  */
 typedef struct {
 	const uint8_t *next_in; /**< Pointer to the next input byte. */
diff --git a/src/liblzma/api/lzma/container.h b/src/liblzma/api/lzma/container.h
index 2b719b04..9535ffa9 100644
--- a/src/liblzma/api/lzma/container.h
+++ b/src/liblzma/api/lzma/container.h
@@ -1,5 +1,5 @@
 /**
- * \file        lzma/FIXME.h
+ * \file        lzma/container.h
  * \brief       File formats
  *
  * \author      Copyright (C) 1999-2008 Igor Pavlov
@@ -255,7 +255,9 @@ extern lzma_ret lzma_auto_decoder(
 /**
  * \brief       Initializes decoder for LZMA_Alone file
  *
- * The LZMA_Alone decoder supports LZMA_SYNC_FLUSH. FIXME
+ * Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH.
+ * There is no need to use LZMA_FINISH, but allowing it may simplify
+ * certain types of applications.
  *
  * \return      - LZMA_OK
  *              - LZMA_MEM_ERROR
diff --git a/src/liblzma/lz/lz_encoder.c b/src/liblzma/lz/lz_encoder.c
index 6a39d0f5..067f12c7 100644
--- a/src/liblzma/lz/lz_encoder.c
+++ b/src/liblzma/lz/lz_encoder.c
@@ -143,8 +143,7 @@ fill_window(lzma_coder *coder, lzma_allocator *allocator, const uint8_t *in,
 		coder->mf.read_pos -= pending;
 
 		// Call the skip function directly instead of using
-		// lz_dict_skip(), since we don't want to touch
-		// mf->read_ahead.
+		// mf_skip(), since we don't want to touch mf->read_ahead.
 		coder->mf.skip(&coder->mf, pending);
 	}
 
diff --git a/src/liblzma/lz/lz_encoder.h b/src/liblzma/lz/lz_encoder.h
index 8442dfa0..373cc01b 100644
--- a/src/liblzma/lz/lz_encoder.h
+++ b/src/liblzma/lz/lz_encoder.h
@@ -95,12 +95,12 @@ struct lzma_mf_s {
 	//////////////////
 
 	/// Find matches. Returns the number of distance-length pairs written
-	/// to the matches array. This is called only via lzma_mf_find.
+	/// to the matches array. This is called only via lzma_mf_find().
 	uint32_t (*find)(lzma_mf *mf, lzma_match *matches);
 
 	/// Skips num bytes. This is like find() but doesn't make the
 	/// distance-length pairs available, thus being a little faster.
-	/// This is called only via mf_skip function.
+	/// This is called only via mf_skip().
 	void (*skip)(lzma_mf *mf, uint32_t num);
 
 	uint32_t *hash;
@@ -117,7 +117,7 @@ struct lzma_mf_s {
 
 	/// Maximum length of a match supported by the LZ-based encoder.
 	/// If the longest match found by the match finder is find_len_max,
-	/// lz_dict_find() tries to expand it up to match_len_max bytes.
+	/// mf_find() tries to expand it up to match_len_max bytes.
 	uint32_t match_len_max;
 
 	/// When running out of input, binary tree match finders need to know
@@ -177,10 +177,10 @@ typedef struct {
 // also take longer.
 //
 // A single encoder loop in the LZ-based encoder may call the match finder
-// (lz_dict_find() or lz_dict_skip()) at maximum of after_size times.
-// In other words, a single encoder loop may advance lz_dict.read_pos at
+// (mf_find() or mf_skip()) at maximum of after_size times.
+// In other words, a single encoder loop may advance lzma_mf.read_pos at
 // maximum of after_size times. Since matches are looked up to
-// lz_dict.buffer[lz_dict.read_pos + match_len_max - 1], the total
+// lzma_mf.buffer[lzma_mf.read_pos + match_len_max - 1], the total
 // amount of extra buffer needed after dictionary_size becomes
 // after_size + match_len_max.
 //
diff --git a/src/liblzma/lz/lz_encoder_mf.c b/src/liblzma/lz/lz_encoder_mf.c
index 208bb2ae..d82681b3 100644
--- a/src/liblzma/lz/lz_encoder_mf.c
+++ b/src/liblzma/lz/lz_encoder_mf.c
@@ -244,7 +244,7 @@ do { \
 ///
 /// \param      len_limit       Don't look for matches longer than len_limit.
 /// \param      pos             lzma_mf.read_pos + lzma_mf.offset
-/// \param      cur             Pointer to current byte (lzma_dict_ptr(mf))
+/// \param      cur             Pointer to current byte (mf_ptr(mf))
 /// \param      cur_match       Start position of the current match candidate
 /// \param      loops           Maximum length of the hash chain
 /// \param      son             lzma_mf.son (contains the hash chain)