Add doxygen annotations to all public headers

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

1 files changed, 130 insertions, 13 deletions

diff --git a/include/sqfs/meta_writer.h b/include/sqfs/meta_writer.h
index b3da355..c0d5716 100644
--- a/include/sqfs/meta_writer.h
+++ b/include/sqfs/meta_writer.h
@@ -22,42 +22,159 @@
 
 #include "sqfs/predef.h"
 
+/**
+ * @file meta_writer.h
+ *
+ * @brief Contains declarations for the @ref sqfs_meta_writer_t.
+ */
+
+/**
+ * @struct sqfs_meta_writer_t
+ *
+ * @brief Abstracts generating of meta data blocks, either in memory or
+ *        directly on disk.
+ *
+ * SquashFS stores meta data by dividing it into fixed size (8k) chunks
+ * that are written to disk with a small header indicating the on-disk
+ * size and whether it is compressed or not.
+ *
+ * Data written to meta data blocks doesn't have to be alligned, i.e.
+ * SquashFS doesn't care if an object is written across two blocks.
+ *
+ * The main task of the meta data writer is to provide a simple append
+ * function that transparently takes care of chopping data up into blocks,
+ * compressing the blocks and pre-pending a header.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* Create a meta data reader using a given compressor to compress data.
-   Internally prints error message to stderr on failure.
-   If keep_in_mem is true, the blocks are collected in memory and must
-   be explicitly flushed to disk using meta_write_write_to_file.
-*/
+/**
+ * @brief Create a meta data writer.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * @note The meta writer internally keeps references to the pointers passed
+ *       to this function, so don't destroy them before destroying the
+ *       meta writer.
+ *
+ * @param file An output file to write the data to.
+ * @param cmp A compressor to use.
+ * @param keep_in_memory Set to true to store the compressed blocks
+ *                       internally until they are explicilty told
+ *                       to write them to disk.
+ *
+ * @return A pointer to a meta writer on success, NULL on allocation failure.
+ */
 SQFS_API sqfs_meta_writer_t *sqfs_meta_writer_create(sqfs_file_t *file,
 						     sqfs_compressor_t *cmp,
 						     bool keep_in_mem);
 
+/**
+ * @brief Destroy a meta data writer and free all memory used by it.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * @param m A pointer to a meta data writer.
+ */
 SQFS_API void sqfs_meta_writer_destroy(sqfs_meta_writer_t *m);
 
-/* Compress and flush the currently unfinished block to disk. Returns 0 on
-   success, internally prints error message to stderr on failure */
+/**
+ * @brief Finish the current block, even if it isn't full yet.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * This function forces the meta writer to compress and store the block it
+ * is currently writing to, even if it isn't full yet, and either write it
+ * out to disk (or append it to the in memory chain if told to keep blocks
+ * in memory).
+ *
+ * @param m A pointer to a meta data writer.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_meta_writer_flush(sqfs_meta_writer_t *m);
 
-/* Returns 0 on success. Prints error message to stderr on failure. */
+/**
+ * @brief Finish the current block, even if it isn't full yet.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * This function forces reads a speicifed number of bytes from a given data
+ * block and appends it to the meta data block that the writer is currently
+ * working on. If the block becomes full, it is compressed, written to disk
+ * and a new block is started that the remaining data is written to.
+ *
+ * @param m A pointer to a meta data writer.
+ * @param data A pointer to a chunk of data to append to the writer.
+ * @param size The number of data bytes to append.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_meta_writer_append(sqfs_meta_writer_t *m, const void *data,
 				     size_t size);
 
-/* Query the current block start position and offset within the block */
+/**
+ * @brief Query the current block start position and offset within the block
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * Get the byte offset relative to the first block that the current block will
+ * start at once it is written to disk and get the byte offset within this
+ * block that the next call to @ref sqfs_meta_writer_append will start writing
+ * data at.
+ *
+ * @param m A pointer to a meta data writer.
+ * @param block_start Returns the offset of the current block from the first.
+ * @param offset Returns an offset into the current block where the next write
+ *               starts.
+ */
 SQFS_API void sqfs_meta_writer_get_position(const sqfs_meta_writer_t *m,
 					    uint64_t *block_start,
 					    uint32_t *offset);
 
-/* Reset all internal state, including the current block start position. */
+/**
+ * @brief Reset all internal state, including the current block start position.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * This functions forces the meta data writer to forget everything that
+ * happened since it was created, so it can be recycled.
+ *
+ * The data written is not lost, unless it was kept in memory and never written
+ * out to disk.
+ */
 SQFS_API void sqfs_meta_writer_reset(sqfs_meta_writer_t *m);
 
-/* If created with keep_in_mem true, write the collected blocks to disk.
-   Does not flush the current block. Writes error messages to stderr and
-   returns non-zero on failure. */
+/**
+ * @brief Write all blocks collected in memory to disk
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * If the meta writer was created with the flag set to store blocks in
+ * memory instead of writing them to disk, calling this function forces
+ * the meta writer to write out all blocks it collected so far.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_meta_write_write_to_file(sqfs_meta_writer_t *m);
 
+/**
+ * @brief A convenience function for encoding and writing an inode
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * The SquashFS inode table is essentially a series of meta data blocks
+ * containing variable sized inodes. This function takes a generic inode
+ * structure, encodes it and writes the result to a meta data writer
+ * using @ref sqfs_meta_writer_append internally.
+ *
+ * @param iw A pointer to a meta data writer.
+ * @param n A pointer to an inode.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_meta_writer_write_inode(sqfs_meta_writer_t *iw,
 					  sqfs_inode_generic_t *n);