Comment on all the things

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

1 files changed, 45 insertions, 0 deletions

diff --git a/include/frag_reader.h b/include/frag_reader.h
index 6495f5b..8a3d4cc 100644
--- a/include/frag_reader.h
+++ b/include/frag_reader.h
@@ -8,6 +8,11 @@
 #include <stdint.h>
 #include <stddef.h>
 
+/**
+ * @struct frag_reader_t
+ *
+ * @brief A simple interface for accessing fragments in a SquashFS image
+ */
 typedef struct {
 	sqfs_fragment_t *tbl;
 	size_t num_fragments;
@@ -20,11 +25,51 @@ typedef struct {
 	uint8_t buffer[];
 } frag_reader_t;
 
+/**
+ * @brief Create a fragment reader
+ *
+ * @memberof frag_reader_t
+ *
+ * This function internally reads and decodes the fragment table from the
+ * image and prints error messages to stderr on the way if it fails.
+ *
+ * @param super A pointer to the SquashFS super block read from the image
+ * @param fd    A file descriptor of opened the SquashFS image
+ * @param cmp   A pointer to a compressor object to be used for reading meta
+ *              data blocks from the image.
+ *
+ * @return A pointer to a new fragment reader or NULL on failure
+ */
 frag_reader_t *frag_reader_create(sqfs_super_t *super, int fd,
 				  compressor_t *cmp);
 
+/**
+ * @brief Destroy a fragment reader and free all memory it uses
+ *
+ * @memberof frag_reader_t
+ *
+ * @param f A pointer to a fragment reader object
+ */
 void frag_reader_destroy(frag_reader_t *f);
 
+/**
+ * @brief Read tail-end packed data from a fragment
+ *
+ * @memberof frag_reader_t
+ *
+ * This function internally takes care of loading and uncompressing the
+ * fragment block (which is skipped if it has already been loaded earlier).
+ * It prints error messages to stderr on the way if it fails, including such
+ * errors as trying to index beyond the fragment table.
+ *
+ * @param f      A pointer to a fragment reader object
+ * @param index  A fragment index such as stored in an inode
+ * @param offset A byte offset into the fragment block addressed by the index
+ * @param buffer A pointer to a destination buffer to copy decoded data to
+ * @param size   The number of bytes to copy into the destination buffer
+ *
+ * @return Zero on success, -1 on failure
+ */
 int frag_reader_read(frag_reader_t *f, size_t index, size_t offset,
 		     void *buffer, size_t size);