aboutsummaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorJia Tan <jiat0218@gmail.com>2023-01-21 00:29:38 +0800
committerJia Tan <jiat0218@gmail.com>2023-02-14 20:41:05 +0800
commit816fec125aa74bcef46512c73acc6d9e5a700d15 (patch)
treed0199b0ec55fde19e6a979207b55d8bb1891a2c1 /src
parentliblzma: Add one more missing [out] annotation in vli.h (diff)
downloadxz-816fec125aa74bcef46512c73acc6d9e5a700d15.tar.xz
liblzma: Improve documentation for base.h.
Standardizing each function to always specify params and return values. Also fixed a small grammar mistake.
Diffstat (limited to 'src')
-rw-r--r--src/liblzma/api/lzma/base.h30
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