Update documentation on sqfs_data_writer_t

Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>

2 files changed, 79 insertions, 21 deletions

diff --git a/include/sqfs/block.h b/include/sqfs/block.h
index 0dee934..15d269d 100644
--- a/include/sqfs/block.h
+++ b/include/sqfs/block.h
@@ -37,45 +37,47 @@
 typedef enum {
 	/**
 	 * @brief Only calculate checksum, do NOT compress the data.
+	 *
+	 * If set, the blocks of a file will not be compressed by the
+	 * @ref sqfs_data_writer_t.
 	 */
 	SQFS_BLK_DONT_COMPRESS = 0x0001,
 
 	/**
 	 * @brief Allign the block on disk to device block size.
 	 *
-	 * If set in combination with @ref SQFS_BLK_FIRST_BLOCK, the output
-	 * file is padded to a multiple of the device block size before writing
-	 * the block.
-	 *
-	 * If used with @ref SQFS_BLK_LAST_BLOCK, the output file is padded
-	 * after writing the block.
+	 * If set, the @ref sqfs_data_writer_t will add padding before the
+	 * first block of the affected file and after the last block.
 	 */
 	SQFS_BLK_ALLIGN = 0x0002,
 
 	/**
-	 * @brief Indicates that an equeued block is the first block of a file.
+	 * @brief Set by the @ref sqfs_data_writer_t on the first
+	 *        block of a file.
 	 */
 	SQFS_BLK_FIRST_BLOCK = 0x0800,
 
 	/**
-	 * @brief Indicates that an equeued block is the last block of a file.
+	 * @brief Set by the @ref sqfs_data_writer_t on the last
+	 *        block of a file.
 	 */
 	SQFS_BLK_LAST_BLOCK = 0x1000,
 
 	/**
-	 * @brief Indicates that a block is a tail end of a file and the block
-	 *        processor should take care of fragment packing and accounting.
+	 * @brief Set by the @ref sqfs_data_writer_t to indicate that a block
+	 *        is a tail end of a file and the block.
 	 */
 	SQFS_BLK_IS_FRAGMENT = 0x2000,
 
 	/**
-	 * @brief Set by the block processor on fragment blocks that
+	 * @brief Set by the @ref sqfs_data_writer_t on fragment blocks that
 	 *        it generates.
 	 */
 	SQFS_BLK_FRAGMENT_BLOCK = 0x4000,
 
 	/**
-	 * @brief Set by compressor worker if the block was actually compressed.
+	 * @brief Set by @ref sqfs_data_writer_t if the block was
+	 *        actually compressed.
 	 */
 	SQFS_BLK_IS_COMPRESSED = 0x8000,
 
diff --git a/include/sqfs/data_writer.h b/include/sqfs/data_writer.h
index 37d5479..8cf24ac 100644
--- a/include/sqfs/data_writer.h
+++ b/include/sqfs/data_writer.h
@@ -31,15 +31,15 @@
 /**
  * @struct sqfs_data_writer_t
  *
- * @brief Encapsulates a thread pool based block processor.
+ * @brief Abstracts generating of file data and fragment blocks.
  *
- * The actual implementation may even be non-threaded, depending on the
- * operating system and compile configuration.
+ * This data structure provides a simple begin/append/end interface
+ * to generate file data blocks (see @ref sqfs_data_writer_begin_file,
+ * @ref sqfs_data_writer_append and @ref sqfs_data_writer_end respectively).
  *
- * Either way, the instantiated object processes data blocks that can be
- * enqueued through @ref sqfs_data_writer_enqueue. The completed blocks
- * (compressed and checksumed) are dequeued in the same order and a callback
- * is called for each one.
+ * Internally it takes care of partitioning data in the correct block sizes,
+ * adding tail-ens to fragment blocks, compressing the data, deduplicating data
+ * and finally writing it to disk.
  */
 
 /**
@@ -169,18 +169,74 @@ sqfs_data_writer_t *sqfs_data_writer_create(size_t max_block_size,
  */
 SQFS_API void sqfs_data_writer_destroy(sqfs_data_writer_t *proc);
 
+/**
+ * @brief Start writing a file.
+ *
+ * @memberof sqfs_data_writer_t
+ *
+ * After calling this function, call @ref sqfs_data_writer_append repeatedly to
+ * add data to the file. Finally call @ref sqfs_data_writer_end_file when you
+ * are done. After writing all files, use @ref sqfs_data_writer_finish to wait
+ * until all blocks that are still in flight are done and written to disk.
+ *
+ * The specified inode pointer is kept internally and updated with the
+ * compressed block sizes and final destinations of the file and possible
+ * fragment. You need to make sure it has enough backing-store for all blocks
+ * to come. Furthermore, since there can still be blocks in-flight even after
+ * calling @ref sqfs_data_writer_end_file, the data in the inode may still
+ * change. The only point at which the data writer is guarnteed to not touch
+ * them anymore is after @ref sqfs_data_writer_finish has returned.
+ *
+ * @param proc A pointer to a data writer object.
+ * @param inode The regular file inode representing the file. The data writer
+ *              internally updates it while writing blocks to disk.
+ * @param flags A combination of @ref E_SQFS_BLK_FLAGS that can be used to
+ *              micro manage how the data is processed.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_data_writer_begin_file(sqfs_data_writer_t *proc,
 					 sqfs_inode_generic_t *inode,
 					 uint32_t flags);
 
+/**
+ * @brief Append data to the current file.
+ *
+ * @memberof sqfs_data_writer_t
+ *
+ * Call this after @ref sqfs_data_writer_begin_file to add data to a file.
+ *
+ * @param proc A pointer to a data writer object.
+ * @param data A pointer to a buffer to read data from.
+ * @param size How many bytes should be copied out of the given
+ *             buffer and written to disk.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_data_writer_append(sqfs_data_writer_t *proc,
 				     const void *data, size_t size);
 
+/**
+ * @brief Stop writing the current file and flush everything that is
+ *        buffered internally.
+ *
+ * @memberof sqfs_data_writer_t
+ *
+ * The counter part to @ref sqfs_data_writer_begin_file.
+ *
+ * Even after calling this, there might still be data blocks in-flight.
+ * Use @ref sqfs_data_writer_finish when you are done writing files to force
+ * the remaining blocks to be processed and written to disk.
+ *
+ * @param proc A pointer to a data writer object.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_data_writer_end_file(sqfs_data_writer_t *proc);
 
 /**
- * @brief Wait for the works to finish and finally flush the current
- *        fragment block.
+ * @brief Wait for the in-flight data blocks to finish and finally flush the
+ *        current fragment block.
  *
  * @memberof sqfs_data_writer_t
  *