Add doxygen annotations to all public headers

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

1 files changed, 129 insertions, 13 deletions

diff --git a/include/sqfs/meta_reader.h b/include/sqfs/meta_reader.h
index 1a9e869..989e857 100644
--- a/include/sqfs/meta_reader.h
+++ b/include/sqfs/meta_reader.h
@@ -22,46 +22,162 @@
 
 #include "sqfs/predef.h"
 
+/**
+ * @file meta_reader.h
+ *
+ * @brief Contains declarations for the @ref sqfs_meta_reader_t.
+ */
+
+/**
+ * @struct sqfs_meta_reader_t
+ *
+ * @brief Abstracts reading of meta data blocks.
+ *
+ * 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 read is to provide a simple read and seek
+ * functions that transparently take care of fetching and uncompressing blocks
+ * from disk and reading transparently across block boarders if required.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* Create a meta data reader using a given compressor to extract data.
-   Internally prints error message to stderr on failure.
-
-   Start offset and limit can be specified to do bounds checking against
-   a subregion of the filesystem image.
-*/
+/**
+ * @brief Create a meta data reader
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * @param file A pointer to a file object to read from
+ * @param cmp A compressor to use for unpacking compressed meta data blocks
+ * @param start A lower limit for the blocks to be read. Every seek to an offset
+ *              below that is interpreted as an out-of-bounds read.
+ * @param limit An upper limit for the blocks to read. Every seek to an offset
+ *              afer that is interpreted as an out-of-bounds read.
+ *
+ * @return A pointer to a meta data reader on success, NULL on
+ *         allocation failure.
+ */
 SQFS_API sqfs_meta_reader_t *sqfs_meta_reader_create(sqfs_file_t *file,
 						     sqfs_compressor_t *cmp,
 						     uint64_t start,
 						     uint64_t limit);
 
+/**
+ * @brief Destroy a meta data reader and free all memory used by it.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * @param m A pointer to a meta data reader.
+ */
 SQFS_API void sqfs_meta_reader_destroy(sqfs_meta_reader_t *m);
 
-/* Returns 0 on success. Internally prints to stderr on failure */
+/**
+ * @brief Seek to a specific meta data block and offset.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * The underlying block is fetched from disk and uncompressed, unless it
+ * already is the current block.
+ *
+ * @param m A pointer to a meta data reader.
+ * @param block_start Absolute position where the block header can be found.
+ * @param offset A byte offset into the uncompressed block.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_meta_reader_seek(sqfs_meta_reader_t *m, uint64_t block_start,
 				   size_t offset);
 
+/**
+ * @brief Get the current position that the next read will read from.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * @param m A pointer to a meta data reader.
+ * @param block_start Absolute position where the current block is.
+ * @param offset A byte offset into the uncompressed block.
+ */
 SQFS_API void sqfs_meta_reader_get_position(sqfs_meta_reader_t *m,
 					    uint64_t *block_start,
 					    size_t *offset);
 
-/* Returns 0 on success. Internally prints to stderr on failure */
+/**
+ * @brief Read a chunk of data from a meta data reader.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * If the meta data reader reaches the end of the current block before filling
+ * the destination buffer, it transparently reads the next block from disk and
+ * uncompresses it.
+ *
+ * @param m A pointer to a meta data reader.
+ * @param data A pointer to copy the data to.
+ * @param size The numbre of bytes to read.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_meta_reader_read(sqfs_meta_reader_t *m, void *data,
 				   size_t size);
 
-/* Returns 0 on success. Internally prints to stderr on failure */
+/**
+ * @brief Read and decode a directory header from a meta data reader.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * This is a convenience function on to of @ref sqfs_meta_reader_read that
+ * reads and decodes a directory header from a meta data block.
+ *
+ * @param m A pointer to a meta data reader.
+ * @param hdr A pointer to a directory header to fill.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_meta_reader_read_dir_header(sqfs_meta_reader_t *m,
 					      sqfs_dir_header_t *hdr);
 
-/* Entry can be freed with a single free() call.
-   The function internally prints to stderr on failure */
+/**
+ * @brief Read and decode a directory header from a meta data reader.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * This is a convenience function on to of @ref sqfs_meta_reader_read that
+ * reads and decodes a directory entry.
+ *
+ * @param m A pointer to a meta data reader.
+ * @param ent Returns a pointer to a directory entry. Can be released with a
+ *            single free() call.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API int sqfs_meta_reader_read_dir_ent(sqfs_meta_reader_t *m,
 					   sqfs_dir_entry_t **ent);
 
-/* Inode can be freed with a single free() call.
-   The function internally prints error message to stderr on failure. */
+/**
+ * @brief Read and decode an inode from a meta data reader.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * This is a convenience function on to of @ref sqfs_meta_reader_seek and
+ * @ref sqfs_meta_reader_read that reads and decodes an inode.
+ *
+ * @param ir A pointer to a meta data reader.
+ * @param super A pointer to the super block, required for figuring out the
+ *              size of file inodes.
+ * @param block_start The meta data block to seek to for reading the inode.
+ * @param offset A byte offset within the uncompressed block where the
+ *               inode is.
+ * @param out Returns a pointer to an inode. Can be released with a
+ *            single free() call.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
 SQFS_API
 int sqfs_meta_reader_read_inode(sqfs_meta_reader_t *ir, sqfs_super_t *super,
 				uint64_t block_start, size_t offset,