Add more doc comments from zstd.h

Also exposes a couple of methods publicly which are mentioned in the docs

Author: michielp1807

c2rust-lib.rs

@@ -1,3 +1,36 @@
+//! zstd, short for *Zstandard*, is a fast lossless compression algorithm, targeting real-time
+//! compression scenarios at zlib-level and better compression ratios. The zstd compression library
+//! provides in-memory compression and decompression functions.
+//!
+//! The library supports regular compression levels from 1 up to [`ZSTD_maxCLevel`], which is
+//! currently 22. Levels >= 20, labeled `--ultra`, should be used with caution, as they require
+//! more memory. The library also offers negative compression levels, which extend the range of
+//! speed vs. ratio preferences. The lower the level, the faster the speed (at the cost of
+//! compression).
+//!
+//! (De-)compression can be done in:
+//!   - a single step (described as *Simple API*) using [`ZSTD_compress`] and [`ZSTD_decompress`]
+//!   - a single step, reusing a context (described as *Explicit context*) using
+//!     [`ZSTD_createCCtx`] and [`ZSTD_createDCtx`] to create the context, and using
+//!     [`ZSTD_compressCCtx`] and [`ZSTD_decompressDCtx`] to (de-)compress
+//!   - unbounded multiple steps (described as *Streaming compression*), using
+//!     [`ZSTD_createCStream`] and [`ZSTD_createDStream`] to create a stream, [`ZSTD_initCStream`]
+//!     and [`ZSTD_initDStream`] to (re-)initialize the stream for (de)-compression, and
+//!     [`ZSTD_compressStream2`] and [`ZSTD_decompressStream`] to consume input
+//!
+//! The compression ratio achievable on small data can be highly improved using a dictionary.
+//! Dictionary compression can be performed in:
+//!   - a single step (described as *Simple dictionary API*), using [`ZSTD_compress_usingDict`] and
+//!     [`ZSTD_decompress_usingDict`]
+//!   - a single step, reusing a dictionary (described as *Bulk-processing dictionary API*), using
+//!     [`ZSTD_createCDict`] and [`ZSTD_createDDict`] to create a dictionary, and using
+//!     [`ZSTD_compress_usingCDict`] and [`ZSTD_decompress_usingDDict`] to (de-)compress using the
+//!     dictionary
+//!
+//! Advanced experimental APIs should never be used with a dynamically-linked library. They are not
+//! "stable"; their definitions or signatures may change in the future. Only static linking is
+//! allowed.
+
 #![allow(non_camel_case_types)]
 #![allow(non_snake_case)]
 #![allow(non_upper_case_globals)]
@@ -78,8 +111,8 @@ pub use crate::lib::zstd::{
 
 pub use crate::lib::decompress::{
     zstd_ddict::{
-        ZSTD_DDict, ZSTD_createDDict, ZSTD_createDDict_byReference, ZSTD_freeDDict,
-        ZSTD_getDictID_fromDDict, ZSTD_sizeof_DDict,
+        ZSTD_DDict, ZSTD_createDDict, ZSTD_createDDict_byReference, ZSTD_estimateDDictSize,
+        ZSTD_freeDDict, ZSTD_getDictID_fromDDict, ZSTD_sizeof_DDict,
     },
     zstd_decompress::{
         ZSTD_DCtx_getParameter, ZSTD_DCtx_loadDictionary, ZSTD_DCtx_refDDict, ZSTD_DCtx_refPrefix,
@@ -116,18 +149,18 @@ pub use crate::lib::compress::zstd_compress::{
     ZSTD_CDict, ZSTD_CStreamInSize, ZSTD_CStreamOutSize, ZSTD_EndDirective, ZSTD_cParam_getBounds,
     ZSTD_compress, ZSTD_compress2, ZSTD_compressBlock, ZSTD_compressBound, ZSTD_compressCCtx,
     ZSTD_compressStream, ZSTD_compressStream2, ZSTD_compress_usingCDict, ZSTD_compress_usingDict,
-    ZSTD_copyCCtx, ZSTD_createCCtx, ZSTD_createCDict, ZSTD_createCDict_byReference, ZSTD_endStream,
-    ZSTD_flushStream, ZSTD_freeCCtx, ZSTD_freeCDict, ZSTD_getBlockSize, ZSTD_getDictID_fromCDict,
-    ZSTD_getFrameProgression, ZSTD_initCStream, ZSTD_initCStream_srcSize,
-    ZSTD_initCStream_usingCDict, ZSTD_initCStream_usingDict, ZSTD_maxCLevel, ZSTD_minCLevel,
-    ZSTD_sequenceBound, ZSTD_sizeof_CCtx, ZSTD_sizeof_CDict, ZSTD_BLOCKSIZE_MAX_MIN,
-    ZSTD_BLOCKSPLITTER_LEVEL_MAX, ZSTD_CHAINLOG_MAX_32, ZSTD_CHAINLOG_MAX_64, ZSTD_CHAINLOG_MIN,
-    ZSTD_HASHLOG_MIN, ZSTD_LDM_BUCKETSIZELOG_MAX, ZSTD_LDM_BUCKETSIZELOG_MIN, ZSTD_LDM_HASHLOG_MIN,
-    ZSTD_LDM_HASHRATELOG_MIN, ZSTD_LDM_MINMATCH_MAX, ZSTD_LDM_MINMATCH_MIN, ZSTD_MINMATCH_MAX,
-    ZSTD_MINMATCH_MIN, ZSTD_OVERLAPLOG_MAX, ZSTD_OVERLAPLOG_MIN, ZSTD_SEARCHLOG_MIN,
-    ZSTD_SKIPPABLEHEADERSIZE, ZSTD_SRCSIZEHINT_MIN, ZSTD_TARGETCBLOCKSIZE_MAX,
-    ZSTD_TARGETCBLOCKSIZE_MIN, ZSTD_TARGETLENGTH_MAX, ZSTD_TARGETLENGTH_MIN,
-    ZSTD_WINDOWLOG_LIMIT_DEFAULT, ZSTD_WINDOWLOG_MIN,
+    ZSTD_copyCCtx, ZSTD_createCCtx, ZSTD_createCDict, ZSTD_createCDict_byReference,
+    ZSTD_createCStream, ZSTD_endStream, ZSTD_flushStream, ZSTD_freeCCtx, ZSTD_freeCDict,
+    ZSTD_getBlockSize, ZSTD_getDictID_fromCDict, ZSTD_getFrameProgression, ZSTD_initCStream,
+    ZSTD_initCStream_srcSize, ZSTD_initCStream_usingCDict, ZSTD_initCStream_usingDict,
+    ZSTD_maxCLevel, ZSTD_minCLevel, ZSTD_sequenceBound, ZSTD_sizeof_CCtx, ZSTD_sizeof_CDict,
+    ZSTD_BLOCKSIZE_MAX_MIN, ZSTD_BLOCKSPLITTER_LEVEL_MAX, ZSTD_CHAINLOG_MAX_32,
+    ZSTD_CHAINLOG_MAX_64, ZSTD_CHAINLOG_MIN, ZSTD_HASHLOG_MIN, ZSTD_LDM_BUCKETSIZELOG_MAX,
+    ZSTD_LDM_BUCKETSIZELOG_MIN, ZSTD_LDM_HASHLOG_MIN, ZSTD_LDM_HASHRATELOG_MIN,
+    ZSTD_LDM_MINMATCH_MAX, ZSTD_LDM_MINMATCH_MIN, ZSTD_MINMATCH_MAX, ZSTD_MINMATCH_MIN,
+    ZSTD_OVERLAPLOG_MAX, ZSTD_OVERLAPLOG_MIN, ZSTD_SEARCHLOG_MIN, ZSTD_SKIPPABLEHEADERSIZE,
+    ZSTD_SRCSIZEHINT_MIN, ZSTD_TARGETCBLOCKSIZE_MAX, ZSTD_TARGETCBLOCKSIZE_MIN,
+    ZSTD_TARGETLENGTH_MAX, ZSTD_TARGETLENGTH_MIN, ZSTD_WINDOWLOG_LIMIT_DEFAULT, ZSTD_WINDOWLOG_MIN,
 };
 
 pub mod internal {

lib/common/zstd_common.rs

@@ -5,30 +5,66 @@ use crate::lib::common::error_private::{
 };
 use crate::lib::zstd::*;
 
+/// Get the zstd version number
+///
+/// # Returns
+///
+/// - the runtime library version, as `(MAJOR*100*100 + MINOR*100 + RELEASE)`
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_versionNumber))]
 pub const extern "C" fn ZSTD_versionNumber() -> core::ffi::c_uint {
     ZSTD_VERSION_NUMBER as core::ffi::c_uint
 }
+
+/// Get a zstd version string
+///
+/// # Returns
+///
+/// - the runtime library version, like "1.5.8"
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_versionString))]
 pub const extern "C" fn ZSTD_versionString() -> *const core::ffi::c_char {
     c"1.5.8".as_ptr()
 }
+
+/// Most functions returning a `size_t` value can be tested for errors, using [`ZSTD_isError`].
+///
+/// # Returns
+///
+/// - 1 if the provided code is an error
+/// - 0 otherwise
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_isError))]
 pub const extern "C" fn ZSTD_isError(code: size_t) -> core::ffi::c_uint {
     ERR_isError(code) as _
 }
+
+/// Provides a readable error string from a function result
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_getErrorName))]
 pub extern "C" fn ZSTD_getErrorName(code: size_t) -> *const core::ffi::c_char {
     ERR_getErrorName(code)
 }
+
+/// Convert a result into an error code, which can be compared to the errors enum list
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_getErrorCode))]
 pub extern "C" fn ZSTD_getErrorCode(code: size_t) -> ZSTD_ErrorCode {
     ERR_getErrorCode(code)
 }
+
+/// Provides a readable error string from an error code
+///
+/// Unlike [`ZSTD_getErrorName`], this method should not be used on `size_t` function results
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_getErrorString))]
 pub extern "C" fn ZSTD_getErrorString(code: ZSTD_ErrorCode) -> *const core::ffi::c_char {
     ERR_getErrorString(code)
 }
+
+/// This is mainly used for Zstd's determinism test suite, which is only run when this function
+/// returns 1.
+///
+/// # Returns
+///
+/// - 1 if the library is built using standard compilation flags and participates in determinism
+///   guarantees with other builds of the same version.
+/// - 0 if the library was compiled with non-standard compilation flags that change the output of
+///   the compressor.
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_isDeterministicBuild))]
 pub extern "C" fn ZSTD_isDeterministicBuild() -> core::ffi::c_int {
     true as core::ffi::c_int

lib/decompress/mod.rs

@@ -171,11 +171,15 @@ impl From<u32> for BlockType {
 #[derive(Default)]
 #[repr(C)]
 pub struct ZSTD_FrameHeader {
+    /// if set to [`crate::ZSTD_CONTENTSIZE_UNKNOWN`], it means this field is not available, 0 means "empty"
     pub frameContentSize: core::ffi::c_ulonglong,
+    /// can be very large, up to <= `frameContentSize`
     pub windowSize: core::ffi::c_ulonglong,
     pub blockSizeMax: core::ffi::c_uint,
+    /// if set to [`ZSTD_skippableFrame`], `frameContentSize` is the size of skippable content
     pub frameType: ZSTD_FrameType_e,
     pub headerSize: core::ffi::c_uint,
+    /// for [`ZSTD_skippableFrame`], contains the skippable magic variant \[0-15]
     pub dictID: core::ffi::c_uint,
     pub checksumFlag: core::ffi::c_uint,
     pub _reserved1: core::ffi::c_uint,
@@ -210,6 +214,17 @@ impl Workspace {
 }
 
 pub type ZSTD_DCtx = ZSTD_DCtx_s;
+
+/// Decompression context
+///
+/// When decompressing many times, it is recommended to allocate a context only once, and reuse it
+/// for each successive compression operation. This will make workload friendlier for system's
+/// memory.
+///
+/// You can create a decompression context with [`crate::ZSTD_createDCtx`] and free it with
+/// [`crate::ZSTD_freeDCtx`].
+///
+/// Use one context per thread for parallel execution.
 #[repr(C)]
 pub struct ZSTD_DCtx_s {
     LLTptr: Option<NonNull<SymbolTable<512>>>,

lib/decompress/zstd_ddict.rs

@@ -64,8 +64,12 @@ impl ZSTD_DDict {
 }
 
 pub type ZSTD_dictContentType_e = core::ffi::c_uint;
+/// Refuses to load a dictionary if it does not respect Zstandard's specification, starting with
+/// [`ZSTD_MAGIC_DICTIONARY`]
 pub const ZSTD_dct_fullDict: ZSTD_dictContentType_e = 2;
+/// Ensures dictionary is always loaded as `rawContent`, even if it starts with [`ZSTD_MAGIC_DICTIONARY`]
 pub const ZSTD_dct_rawContent: ZSTD_dictContentType_e = 1;
+/// Dictionary is "full" when starting with [`ZSTD_MAGIC_DICTIONARY`], otherwise it is "rawContent"
 pub const ZSTD_dct_auto: ZSTD_dictContentType_e = 0;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -75,7 +79,9 @@ enum DictLoadMethod {
 }
 
 pub type ZSTD_dictLoadMethod_e = core::ffi::c_uint;
+/// Copy dictionary content internally
 pub const ZSTD_dlm_byCopy: ZSTD_dictLoadMethod_e = DictLoadMethod::ByCopy as _;
+/// Reference dictionary content -- the dictionary buffer must outlive its users
 pub const ZSTD_dlm_byRef: ZSTD_dictLoadMethod_e = DictLoadMethod::ByRef as _;
 
 pub const ZSTD_MAGIC_DICTIONARY: core::ffi::c_uint = 0xec30a437 as core::ffi::c_uint;
@@ -231,7 +237,15 @@ pub unsafe extern "C" fn ZSTD_createDDict_advanced(
 
 /// Create a digested dictionary, to start decompression without startup delay.
 ///
-/// `dict` content is copied inside the [`ZSTD_DDict`], so `dict` can be released after [`ZSTD_DDict`] creation
+/// The `dict`'s content is copied inside the [`ZSTD_DDict`], so `dict` can be released after
+/// [`ZSTD_DDict`] creation.
+///
+/// The DDict can be freed using [`ZSTD_freeDDict`].
+///
+/// # Returns
+///
+/// - a [`ZSTD_DDict`] if it was successfully created
+/// - NULL if there was an error creating the dictionary
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_createDDict))]
 pub unsafe extern "C" fn ZSTD_createDDict(
     dict: *const core::ffi::c_void,
@@ -306,6 +320,9 @@ pub unsafe extern "C" fn ZSTD_initStaticDDict(
     ddict
 }
 
+/// Free the memory allocated with [`ZSTD_createDDict`].
+///
+/// If a NULL pointer is passed, no operation is performed.
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_freeDDict))]
 pub unsafe extern "C" fn ZSTD_freeDDict(ddict: *mut ZSTD_DDict) -> size_t {
     if ddict.is_null() {
@@ -336,6 +353,12 @@ pub const extern "C" fn ZSTD_estimateDDictSize(
     }
 }
 
+/// Get the _current_ memory usage of the [`ZSTD_DDict`]
+///
+/// # Returns
+///
+/// - the size of the DDict, including the size of the DDict's `dictBuffer` if present
+/// - 0 if the `ddict` is NULL
 #[cfg_attr(feature = "export-symbols", export_name = crate::prefix!(ZSTD_sizeof_DDict))]
 pub unsafe extern "C" fn ZSTD_sizeof_DDict(ddict: *const ZSTD_DDict) -> size_t {
     if ddict.is_null() {