revi-archive/xz-archive
1
0
Fork 0
mirror of https://git.tukaani.org/xz.git synced 2024-04-04 12:36:23 +02:00
Code Activity

liblzma: Improve documentation for base.h.

Browse source 
Standardizing each function to always specify params and return values.
Also fixed a small grammar mistake.
This commit is contained in:
Jia Tan 2023-01-21 00:29:38 +08:00
parent 2287d56683
commit 135d5a1a65
1 changed files with 25 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
src/liblzma/api/lzma/base.h
View file

@ -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