@@ -185,12 +185,15 @@ LZ4File_get_error(CompressFileHandle *CFH)
185185}
186186
187187/*
188- * Prepare an already alloc'ed LZ4File struct for subsequent calls.
188+ * Prepare an already alloc'ed LZ4File struct for subsequent calls (either
189+ * compression or decompression).
189190 *
190- * It creates the necessary contexts for the operations. When compressing,
191- * it additionally writes the LZ4 header in the output stream.
191+ * It creates the necessary contexts for the operations. When compressing data
192+ * (indicated by compressing=true), it additionally writes the LZ4 header in the
193+ * output stream.
192194 *
193- * Returns true on success and false on error.
195+ * Returns true on success. In case of a failure returns false, and stores the
196+ * error code in fs->errcode.
194197 */
195198static bool
196199LZ4File_init (LZ4File * fs ,int size ,bool compressing )
@@ -203,9 +206,15 @@ LZ4File_init(LZ4File *fs, int size, bool compressing)
203206fs -> compressing = compressing ;
204207fs -> inited = true;
205208
209+ /* When compressing, write LZ4 header to the output stream. */
206210if (fs -> compressing )
207211{
208212fs -> buflen = LZ4F_compressBound (DEFAULT_IO_BUFFER_SIZE ,& fs -> prefs );
213+
214+ /*
215+ * LZ4F_compressBegin requires a buffer that is greater or equal to
216+ * LZ4F_HEADER_SIZE_MAX. Verify that the requirement is met.
217+ */
209218if (fs -> buflen < LZ4F_HEADER_SIZE_MAX )
210219fs -> buflen = LZ4F_HEADER_SIZE_MAX ;
211220
@@ -255,9 +264,12 @@ LZ4File_init(LZ4File *fs, int size, bool compressing)
255264/*
256265 * Read already decompressed content from the overflow buffer into 'ptr' up to
257266 * 'size' bytes, if available. If the eol_flag is set, then stop at the first
258- * occurrence of thenew line char prior to 'size' bytes.
267+ * occurrence of thenewline char prior to 'size' bytes.
259268 *
260269 * Any unread content in the overflow buffer is moved to the beginning.
270+ *
271+ * Returns the number of bytes read from the overflow buffer (and copied into
272+ * the 'ptr' buffer), or 0 if the overflow buffer is empty.
261273 */
262274static int
263275LZ4File_read_overflow (LZ4File * fs ,void * ptr ,int size ,bool eol_flag )
@@ -297,6 +309,9 @@ LZ4File_read_overflow(LZ4File *fs, void *ptr, int size, bool eol_flag)
297309 * at an overflow buffer within LZ4File. Of course, when the function is
298310 * called, it will first try to consume any decompressed content already
299311 * present in the overflow buffer, before decompressing new content.
312+ *
313+ * Returns the number of bytes of decompressed data copied into the ptr
314+ * buffer, or -1 in case of error.
300315 */
301316static int
302317LZ4File_read_internal (LZ4File * fs ,void * ptr ,int ptrsize ,bool eol_flag )