From 816fec125aa74bcef46512c73acc6d9e5a700d15 Mon Sep 17 00:00:00 2001 From: Jia Tan Date: Sat, 21 Jan 2023 00:29:38 +0800 Subject: [PATCH] liblzma: Improve documentation for base.h. Standardizing each function to always specify params and return values. Also fixed a small grammar mistake. --- src/liblzma/api/lzma/base.h | 30 +++++++++++++++++++++++++----- 1 file 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