liblzma: Improve documentation in lzma12.h.

All functions now explicitly specify parameter and return values.
This commit is contained in:
Jia Tan 2023-02-14 21:50:16 +08:00
parent 43ec344c86
commit 13d99e75a5
1 changed files with 23 additions and 9 deletions

View File

@ -138,16 +138,20 @@ typedef enum {
/** /**
* \brief Test if given match finder is supported * \brief Test if given match finder is supported
* *
* Return true if the given match finder is supported by this liblzma build. * It is safe to call this with a value that isn't listed in
* Otherwise false is returned. It is safe to call this with a value that * lzma_match_finder enumeration; the return value will be false.
* isn't listed in lzma_match_finder enumeration; the return value will be
* false.
* *
* There is no way to list which match finders are available in this * There is no way to list which match finders are available in this
* particular liblzma version and build. It would be useless, because * particular liblzma version and build. It would be useless, because
* a new match finder, which the application developer wasn't aware, * a new match finder, which the application developer wasn't aware,
* could require giving additional options to the encoder that the older * could require giving additional options to the encoder that the older
* match finders don't need. * match finders don't need.
*
* \param match_finder Match finder ID
*
* \return lzma_bool:
* - true if the match finder is supported by this liblzma build.
* - false otherwise.
*/ */
extern LZMA_API(lzma_bool) lzma_mf_is_supported(lzma_match_finder match_finder) extern LZMA_API(lzma_bool) lzma_mf_is_supported(lzma_match_finder match_finder)
lzma_nothrow lzma_attr_const; lzma_nothrow lzma_attr_const;
@ -182,14 +186,20 @@ typedef enum {
/** /**
* \brief Test if given compression mode is supported * \brief Test if given compression mode is supported
* *
* Return true if the given compression mode is supported by this liblzma * It is safe to call this with a value that isn't listed in lzma_mode
* build. Otherwise false is returned. It is safe to call this with a value * enumeration; the return value will be false.
* that isn't listed in lzma_mode enumeration; the return value will be false.
* *
* There is no way to list which modes are available in this particular * There is no way to list which modes are available in this particular
* liblzma version and build. It would be useless, because a new compression * liblzma version and build. It would be useless, because a new compression
* mode, which the application developer wasn't aware, could require giving * mode, which the application developer wasn't aware, could require giving
* additional options to the encoder that the older modes don't need. * additional options to the encoder that the older modes don't need.
*
* \param mode Mode ID.
*
* \return lzma_bool:
* - true if the compression mode is supported by this liblzma
* build.
* - false otherwise.
*/ */
extern LZMA_API(lzma_bool) lzma_mode_is_supported(lzma_mode mode) extern LZMA_API(lzma_bool) lzma_mode_is_supported(lzma_mode mode)
lzma_nothrow lzma_attr_const; lzma_nothrow lzma_attr_const;
@ -545,8 +555,12 @@ do { \
* This function is available only if LZMA1 or LZMA2 encoder has been enabled * This function is available only if LZMA1 or LZMA2 encoder has been enabled
* when building liblzma. * when building liblzma.
* *
* \return On success, false is returned. If the preset is not * \param[out] options Pointer to LZMA12 options to be filled
* supported, true is returned. * \param preset Preset value between 0-9 ORed with preset flags
*
* \return lzma_bool:
* - true if the preset is not supported (failure).
* - false otherwise (success).
*/ */
extern LZMA_API(lzma_bool) lzma_lzma_preset( extern LZMA_API(lzma_bool) lzma_lzma_preset(
lzma_options_lzma *options, uint32_t preset) lzma_nothrow; lzma_options_lzma *options, uint32_t preset) lzma_nothrow;