updated comments
diff --git a/lib/zstd.h b/lib/zstd.h
index 5cc40c6..a8b2de1 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -48,7 +48,7 @@
* Simple API
***************************************/
/*! ZSTD_compress() :
- Compresses `src` buffer into already allocated `dst`.
+ Compresses `src` content as a single zstd compressed frame into already allocated `dst`.
Hint : compression runs faster if `dstCapacity` >= `ZSTD_compressBound(srcSize)`.
@return : the number of bytes written into `dst` (<= `dstCapacity),
or an error code if it fails (which can be tested using ZSTD_isError()) */
@@ -56,32 +56,33 @@
const void* src, size_t srcSize,
int compressionLevel);
-/*! ZSTD_getDecompressedSize() :
-* @return : decompressed size as a 64-bits value _if known_, 0 otherwise.
-* note 1 : decompressed size can be very large (64-bits value),
-* potentially larger than what local system can handle as a single memory segment.
-* In which case, it's necessary to use streaming mode to decompress data.
-* note 2 : decompressed size is an optional field, that may not be present.
-* When `return==0`, data to decompress can have any size.
-* In which case, it's necessary to use streaming mode to decompress data.
-* Optionally, application may rely on its own implied limits.
-* (For example, application data could be necessarily cut into blocks <= 16 KB).
-* note 3 : decompressed size could be wrong or intentionally modified !
-* Always ensure result fits within application's authorized limits !
-* Each application can set its own limits.
-* note 4 : when `return==0`, if precise failure cause is needed, use ZSTD_getFrameParams() to know more. */
-ZSTDLIB_API unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);
-
/*! ZSTD_decompress() :
- `compressedSize` : must be the _exact_ size of compressed input, otherwise decompression will fail.
- `dstCapacity` must be equal or larger than originalSize (see ZSTD_getDecompressedSize() ).
- If originalSize is unknown, and if there is no implied application-specific limitations,
- it's preferable to use streaming mode to decompress data.
+ `compressedSize` : must be the _exact_ size of a single compressed frame.
+ `dstCapacity` is an upper bound of originalSize.
+ If user cannot imply a maximum upper bound, it's better to use streaming mode to decompress data.
@return : the number of bytes decompressed into `dst` (<= `dstCapacity`),
or an errorCode if it fails (which can be tested using ZSTD_isError()) */
ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity,
const void* src, size_t compressedSize);
+/*! ZSTD_getDecompressedSize() :
+* 'src' is the start of a zstd compressed frame.
+* @return : content size to be decompressed, as a 64-bits value _if known_, 0 otherwise.
+* note 1 : decompressed size is an optional field, that may not be present, especially in streaming mode.
+* When `return==0`, data to decompress could be any size.
+* In which case, it's necessary to use streaming mode to decompress data.
+* Optionally, application can still use ZSTD_decompress() while relying on implied limits.
+* (For example, data may be necessarily cut into blocks <= 16 KB).
+* note 2 : decompressed size is always present when compression is done with ZSTD_compress()
+* note 3 : decompressed size can be very large (64-bits value),
+* potentially larger than what local system can handle as a single memory segment.
+* In which case, it's necessary to use streaming mode to decompress data.
+* note 4 : If source is untrusted, decompressed size could be wrong or intentionally modified.
+* Always ensure result fits within application's authorized limits.
+* Each application can set its own limits.
+* note 5 : when `return==0`, if precise failure cause is needed, use ZSTD_getFrameParams() to know more. */
+ZSTDLIB_API unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);
+
/*====== Helper functions ======*/
ZSTDLIB_API int ZSTD_maxCLevel(void); /*!< maximum compression level available */