liblzma: Improve documentation for base.h.

Standardizing each function to always specify params and return values.
Also fixed a small grammar mistake.

1 files changed, 25 insertions, 5 deletions

diff --git a/src/liblzma/api/lzma/base.h b/src/liblzma/api/lzma/base.h
index e43bda93..caf488fe 100644
--- a/src/liblzma/api/lzma/base.h
+++ b/src/liblzma/api/lzma/base.h
@@ -278,7 +278,7 @@ typedef enum {
  * \brief       The `action' argument for lzma_code()
  *
  * After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER,
- * or LZMA_FINISH, the same `action' must is used until lzma_code() returns
+ * or LZMA_FINISH, the same `action' must be 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
@@ -625,6 +625,14 @@ typedef struct {
  *
  * See the description of the coder-specific initialization function to find
  * out what `action' values are supported by the coder.
+ *
+ * \param       strm    Pointer to lzma_stream that is at least initialized
+ *                      with LZMA_STREAM_INIT.
+ * \param       action  Action for this function to take. Must be a valid
+ *                      lzma_action enum value.
+ *
+ * \return      Any valid lzma_ret. See the lzma_ret enum description for more
+ *              information.
  */
 extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action)
 		lzma_nothrow lzma_attr_warn_unused_result;
@@ -633,15 +641,15 @@ extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action)
 /**
  * \brief       Free memory allocated for the coder data structures
  *
- * \param       strm    Pointer to lzma_stream that is at least initialized
- *                      with LZMA_STREAM_INIT.
- *
  * After lzma_end(strm), strm->internal is guaranteed to be NULL. No other
  * members of the lzma_stream structure are touched.
  *
  * \note        zlib indicates an error if application end()s unfinished
  *              stream structure. liblzma doesn't do this, and assumes that
  *              application knows what it is doing.
+ *
+ * \param       strm    Pointer to lzma_stream that is at least initialized
+ *                      with LZMA_STREAM_INIT.
  */
 extern LZMA_API(void) lzma_end(lzma_stream *strm) lzma_nothrow;
 
@@ -660,6 +668,11 @@ extern LZMA_API(void) lzma_end(lzma_stream *strm) lzma_nothrow;
  * mode by taking into account the progress made by each thread. In
  * single-threaded mode *progress_in and *progress_out are set to
  * strm->total_in and strm->total_out, respectively.
+ *
+ * \param       strm          Pointer to lzma_stream that is at least
+ *                            initialized with LZMA_STREAM_INIT.
+ * \param[out]  progress_in   Pointer to the number of input bytes processed.
+ * \param[out]  progress_out  Pointer to the number of output bytes processed.
  */
 extern LZMA_API(void) lzma_get_progress(lzma_stream *strm,
 		uint64_t *progress_in, uint64_t *progress_out) lzma_nothrow;
@@ -678,6 +691,9 @@ extern LZMA_API(void) lzma_get_progress(lzma_stream *strm,
  * this may give misleading information if decoding .xz Streams that have
  * multiple Blocks, because each Block can have different memory requirements.
  *
+ * \param       strm    Pointer to lzma_stream that is at least initialized
+ *                      with LZMA_STREAM_INIT.
+ *
  * \return      How much memory is currently allocated for the filter
  *              decoders. If no filter chain is currently allocated,
  *              some non-zero value is still returned, which is less than
@@ -697,6 +713,9 @@ extern LZMA_API(uint64_t) lzma_memusage(const lzma_stream *strm)
  * This function is supported only when *strm has been initialized with
  * a function that takes a memlimit argument.
  *
+ * \param       strm    Pointer to lzma_stream that is at least initialized
+ *                      with LZMA_STREAM_INIT.
+ *
  * \return      On success, the current memory usage limit is returned
  *              (always non-zero). On error, zero is returned.
  */
@@ -720,7 +739,8 @@ extern LZMA_API(uint64_t) lzma_memlimit_get(const lzma_stream *strm)
  * after LZMA_MEMLIMIT_ERROR even if the limit was increased using
  * lzma_memlimit_set(). Other decoders worked correctly.
  *
- * \return      - LZMA_OK: New memory usage limit successfully set.
+ * \return      Possible lzma_ret values:
+ *              - LZMA_OK: New memory usage limit successfully set.
  *              - LZMA_MEMLIMIT_ERROR: The new limit is too small.
  *                The limit was not changed.
  *              - LZMA_PROG_ERROR: Invalid arguments, e.g. *strm doesn't