aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJia Tan <jiat0218@gmail.com>2023-01-27 22:44:06 +0800
committerJia Tan <jiat0218@gmail.com>2023-02-15 00:59:16 +0800
commit43ec344c868f930e96879eb9e49212cce92a9884 (patch)
tree86ab3a986a3e94d7fa0fa8cf2cd3740679173989
parentliblzma: Improve documentation in index.h (diff)
downloadxz-43ec344c868f930e96879eb9e49212cce92a9884.tar.xz
liblzma: Improve documentation in check.h.
All functions now explicitly specify parameter and return values. Also moved the note about SHA-256 functions not being exported to the top of the file.
-rw-r--r--src/liblzma/api/lzma/check.h41
1 files changed, 28 insertions, 13 deletions
diff --git a/src/liblzma/api/lzma/check.h b/src/liblzma/api/lzma/check.h
index c7336ae5..5d793959 100644
--- a/src/liblzma/api/lzma/check.h
+++ b/src/liblzma/api/lzma/check.h
@@ -72,12 +72,17 @@ typedef enum {
/**
* \brief Test if the given Check ID is supported
*
- * Return true if the given Check ID is supported by this liblzma build.
- * Otherwise false is returned. It is safe to call this with a value that
- * is not in the range [0, 15]; in that case the return value is always false.
+ * LZMA_CHECK_NONE and LZMA_CHECK_CRC32 are always supported (even if
+ * liblzma is built with limited features).
*
- * You can assume that LZMA_CHECK_NONE and LZMA_CHECK_CRC32 are always
- * supported (even if liblzma is built with limited features).
+ * \note It is safe to call this with a value that is not in the
+ * range [0, 15]; in that case the return value is always false.
+ *
+ * \param check Check ID
+ *
+ * \return lzma_bool:
+ * - true if Check ID is supported by this liblzma build.
+ * - false otherwise.
*/
extern LZMA_API(lzma_bool) lzma_check_is_supported(lzma_check check)
lzma_nothrow lzma_attr_const;
@@ -91,7 +96,10 @@ extern LZMA_API(lzma_bool) lzma_check_is_supported(lzma_check check)
* the Check field with the specified Check ID. The values are:
* { 0, 4, 4, 4, 8, 8, 8, 16, 16, 16, 32, 32, 32, 64, 64, 64 }
*
- * If the argument is not in the range [0, 15], UINT32_MAX is returned.
+ * \param check Check ID
+ *
+ * \return Size of the Check field in bytes. If the argument is not in
+ * the range [0, 15], UINT32_MAX is returned.
*/
extern LZMA_API(uint32_t) lzma_check_size(lzma_check check)
lzma_nothrow lzma_attr_const;
@@ -127,25 +135,32 @@ extern LZMA_API(uint32_t) lzma_crc32(
*
* Calculate CRC64 using the polynomial from the ECMA-182 standard.
*
- * This function is used similarly to lzma_crc32(). See its documentation.
+ * This function is used similarly to lzma_crc32().
+ *
+ * \param buf Pointer to the input buffer
+ * \param size Size of the input buffer
+ * \param crc Previously returned CRC value. This is used to
+ * calculate the CRC of a big buffer in smaller chunks.
+ * Set to zero when starting a new calculation.
+ *
+ * \return Updated CRC value, which can be passed to this function
+ * again to continue CRC calculation.
*/
extern LZMA_API(uint64_t) lzma_crc64(
const uint8_t *buf, size_t size, uint64_t crc)
lzma_nothrow lzma_attr_pure;
-/*
- * SHA-256 functions are currently not exported to public API.
- * Contact Lasse Collin if you think it should be.
- */
-
-
/**
* \brief Get the type of the integrity check
*
* This function can be called only immediately after lzma_code() has
* returned LZMA_NO_CHECK, LZMA_UNSUPPORTED_CHECK, or LZMA_GET_CHECK.
* Calling this function in any other situation has undefined behavior.
+ *
+ * \param strm Pointer to lzma_stream meeting the above conditions.
+ *
+ * \return Check ID in the lzma_stream, or undefined if called improperly.
*/
extern LZMA_API(lzma_check) lzma_get_check(const lzma_stream *strm)
lzma_nothrow;