From 74e6afc5dc67cb0f630a3d001b1ab4e742baba76 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Thu, 11 Aug 2016 18:55:42 +0200 Subject: minor comments clarification --- lib/lz4frame.h | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/lib/lz4frame.h b/lib/lz4frame.h index bae4016..6a1f987 100644 --- a/lib/lz4frame.h +++ b/lib/lz4frame.h @@ -130,8 +130,7 @@ typedef struct { ***********************************/ size_t LZ4F_compressFrameBound(size_t srcSize, const LZ4F_preferences_t* preferencesPtr); -size_t LZ4F_compressFrame(void* dstBuffer, size_t dstMaxSize, const void* srcBuffer, size_t srcSize, const LZ4F_preferences_t* preferencesPtr); -/* LZ4F_compressFrame() +/*!LZ4F_compressFrame() : * Compress an entire srcBuffer into a valid LZ4 frame, as defined by specification v1.5.1 * The most important rule is that dstBuffer MUST be large enough (dstMaxSize) to ensure compression completion even in worst case. * You can get the minimum value of dstMaxSize by using LZ4F_compressFrameBound() @@ -140,12 +139,13 @@ size_t LZ4F_compressFrame(void* dstBuffer, size_t dstMaxSize, const void* srcBuf * The result of the function is the number of bytes written into dstBuffer. * The function outputs an error code if it fails (can be tested using LZ4F_isError()) */ +size_t LZ4F_compressFrame(void* dstBuffer, size_t dstMaxSize, const void* srcBuffer, size_t srcSize, const LZ4F_preferences_t* preferencesPtr); -/*-******************************** +/*-*********************************** * Advanced compression functions -**********************************/ +*************************************/ typedef struct LZ4F_cctx_s* LZ4F_compressionContext_t; /* must be aligned on 8-bytes */ typedef struct { @@ -222,7 +222,7 @@ size_t LZ4F_compressEnd(LZ4F_compressionContext_t cctx, void* dstBuffer, size_t */ -/*********************************** +/*-********************************* * Decompression functions ***********************************/ @@ -236,11 +236,8 @@ typedef struct { /* Resource management */ -LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_decompressionContext_t* dctxPtr, unsigned version); -LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_decompressionContext_t dctx); -/* LZ4F_createDecompressionContext() : - * The first thing to do is to create an LZ4F_decompressionContext_t object, which will be used in all decompression operations. - * This is achieved using LZ4F_createDecompressionContext(). +/*!LZ4F_createDecompressionContext() : + * Create an LZ4F_decompressionContext_t object, which will be used to track all decompression operations. * The version provided MUST be LZ4F_VERSION. It is intended to track potential breaking differences between different versions. * The function will provide a pointer to a fully allocated and initialized LZ4F_decompressionContext_t object. * The result is an errorCode, which can be tested using LZ4F_isError(). @@ -248,14 +245,13 @@ LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_decompressionContext_t dctx) * The result of LZ4F_freeDecompressionContext() is indicative of the current state of decompressionContext when being released. * That is, it should be == 0 if decompression has been completed fully and correctly. */ +LZ4F_errorCode_t LZ4F_createDecompressionContext(LZ4F_decompressionContext_t* dctxPtr, unsigned version); +LZ4F_errorCode_t LZ4F_freeDecompressionContext(LZ4F_decompressionContext_t dctx); -/* Decompression */ +/*====== Decompression ======*/ -size_t LZ4F_getFrameInfo(LZ4F_decompressionContext_t dctx, - LZ4F_frameInfo_t* frameInfoPtr, - const void* srcBuffer, size_t* srcSizePtr); -/* LZ4F_getFrameInfo() +/*!LZ4F_getFrameInfo() : * This function decodes frame header information (such as max blockSize, frame checksum, etc.). * Its usage is optional. The objective is to extract frame header information, typically for allocation purposes. * A header size is variable and can be from 7 to 15 bytes. It's also possible to input more bytes than that. @@ -267,12 +263,11 @@ size_t LZ4F_getFrameInfo(LZ4F_decompressionContext_t dctx, * (typically, when there is not enough src bytes to fully decode the frame header) * Decompression is expected to resume from where it stopped (srcBuffer + *srcSizePtr) */ +size_t LZ4F_getFrameInfo(LZ4F_decompressionContext_t dctx, + LZ4F_frameInfo_t* frameInfoPtr, + const void* srcBuffer, size_t* srcSizePtr); -size_t LZ4F_decompress(LZ4F_decompressionContext_t dctx, - void* dstBuffer, size_t* dstSizePtr, - const void* srcBuffer, size_t* srcSizePtr, - const LZ4F_decompressOptions_t* dOptPtr); -/* LZ4F_decompress() +/*!LZ4F_decompress() : * Call this function repetitively to regenerate data compressed within srcBuffer. * The function will attempt to decode *srcSizePtr bytes from srcBuffer, into dstBuffer of maximum size *dstSizePtr. * @@ -284,18 +279,23 @@ size_t LZ4F_decompress(LZ4F_decompressionContext_t dctx, * LZ4F_decompress() must be called again, starting from where it stopped (srcBuffer + *srcSizePtr) * The function will check this condition, and refuse to continue if it is not respected. * - * dstBuffer is supposed to be flushed between each call to the function, since its content will be overwritten. - * dst arguments can be changed at will with each consecutive call to the function. + * `dstBuffer` is expected to be flushed between each call to the function, its content will be overwritten. + * `dst` arguments can be changed at will at each consecutive call to the function. * - * The function result is an hint of how many srcSize bytes LZ4F_decompress() expects for next call. + * The function result is an hint of how many `srcSize` bytes LZ4F_decompress() expects for next call. * Schematically, it's the size of the current (or remaining) compressed block + header of next block. * Respecting the hint provides some boost to performance, since it does skip intermediate buffers. - * This is just a hint, you can always provide any srcSize you want. + * This is just a hint though, it's always possible to provide any srcSize. * When a frame is fully decoded, the function result will be 0 (no more data expected). * If decompression failed, function result is an error code, which can be tested using LZ4F_isError(). * * After a frame is fully decoded, dctx can be used again to decompress another frame. */ +size_t LZ4F_decompress(LZ4F_decompressionContext_t dctx, + void* dstBuffer, size_t* dstSizePtr, + const void* srcBuffer, size_t* srcSizePtr, + const LZ4F_decompressOptions_t* dOptPtr); + #if defined (__cplusplus) -- cgit v0.12