Add doxygen annotations to all public headers

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

1 files changed, 228 insertions, 3 deletions

diff --git a/include/sqfs/super.h b/include/sqfs/super.h
index 4556d3d..5e6c00a 100644
--- a/include/sqfs/super.h
+++ b/include/sqfs/super.h
@@ -22,34 +22,172 @@
 
 #include "sqfs/predef.h"
 
+/**
+ * @file super.h
+ *
+ * @brief Contains on-disk data structures, identifiers and functions for the
+ *        SquashFS super block.
+ */
+
 #define SQFS_MAGIC 0x73717368
 #define SQFS_VERSION_MAJOR 4
 #define SQFS_VERSION_MINOR 0
 #define SQFS_DEVBLK_SIZE 4096
 #define SQFS_DEFAULT_BLOCK_SIZE 131072
 
+/**
+ * @struct sqfs_super_t
+ *
+ * @brief The SquashFS super block, located at the beginning of the file system
+ *        to describe the layout of the filesystem.
+ */
 struct sqfs_super_t {
+	/**
+	 * @brief Magic number. Must be set to SQFS_MAGIC.
+	 */
 	uint32_t magic;
+
+	/**
+	 * @brief Total number of inodes.
+	 */
 	uint32_t inode_count;
+
+	/**
+	 * @brief Last time the filesystem was modified.
+	 *
+	 * This field counts seconds (not counting leap seconds) since 00:00,
+	 * Jan 1 1970 UTC. This field is unsigned, so it expires in the year
+	 * 2106 (as opposed to 2038).
+	 */
 	uint32_t modification_time;
+
+	/**
+	 * @brief The data block size in bytes.
+	 *
+	 * Must be a power of 2, no less than 4k and not larger than 1M.
+	 */
 	uint32_t block_size;
+
+	/**
+	 * @brief The number of fragment blocks in the data area.
+	 */
 	uint32_t fragment_entry_count;
+
+	/**
+	 * @brief Identifies the compressor that has been used.
+	 *
+	 * Valid identifiers are in the @ref E_SQFS_COMPRESSOR enum.
+	 */
 	uint16_t compression_id;
+
+	/**
+	 * @brief The log2 of the block_size field for sanity checking
+	 *
+	 * Must be no less than 12 and not larger than 20.
+	 */
 	uint16_t block_log;
+
+	/**
+	 * @brief A combination of @ref E_SQFS_SUPER_FLAGS flags
+	 *
+	 * Most of the flags that can be set here are informative only.
+	 */
 	uint16_t flags;
+
+	/**
+	 * @brief The total number of unique user or group IDs.
+	 */
 	uint16_t id_count;
+
+	/**
+	 * @brief Must be @ref SQFS_VERSION_MAJOR
+	 */
 	uint16_t version_major;
+
+	/**
+	 * @brief Must be @ref SQFS_VERSION_MINOR
+	 */
 	uint16_t version_minor;
+
+	/**
+	 * @brief A reference to the root inode
+	 *
+	 * The bits 16 to 48 hold an offset that is added to inode_table_start
+	 * to get the location of the meta data block containing the inode.
+	 * The lower 16 bits hold a byte offset into the uncompressed block.
+	 */
 	uint64_t root_inode_ref;
+
+	/**
+	 * @brief Total size of the file system in bytes, not counting padding
+	 */
 	uint64_t bytes_used;
+
+	/**
+	 * @brief On-disk location of the ID table
+	 *
+	 * This value must point to a location after the directory table and
+	 * (if present) after the export and fragment tables, but before the
+	 * xattr table.
+	 */
 	uint64_t id_table_start;
+
+	/**
+	 * @brief On-disk location of the extended attribute table (if present)
+	 *
+	 * See @ref sqfs_xattr_reader_t for an overview on how SquashFS stores
+	 * extended attributes on disk.
+	 *
+	 * This value must either point to a location after the ID table, or
+	 * it must be set to 0xFFFFFFFF to indicate the table is not present.
+	 */
 	uint64_t xattr_id_table_start;
+
+	/**
+	 * @brief On-disk location of the first meta data block containing
+	 *        the inodes
+	 *
+	 * This value must point to a location before the directory table.
+	 */
 	uint64_t inode_table_start;
+
+	/**
+	 * @brief On-disk location of the first meta data block containing
+	 *        the directory entries
+	 *
+	 * This value must point to a location after the inode table but
+	 * before the fragment, export, ID and xattr tables.
+	 */
 	uint64_t directory_table_start;
+
+	/**
+	 * @brief On-disk location of the fragment table (if present)
+	 *
+	 * This value must either point to a location after the directory
+	 * table, but before the export, ID and xattr tables, or it must be
+	 * set to 0xFFFFFFFF to indicate that the table is not present.
+	 */
 	uint64_t fragment_table_start;
+
+	/**
+	 * @brief On-disk location of the export table (if present)
+	 *
+	 * This value must either point to a location after directory table
+	 * (and if present after the fragment table), but before the ID table,
+	 * or it must be set to 0xFFFFFFFF to indicate that the table is not
+	 * present.
+	 */
 	uint64_t export_table_start;
 };
 
+/**
+ * @enum E_SQFS_COMPRESSOR
+ *
+ * @brief Set in @ref sqfs_super_t to identify the compresser used by the
+ *        filesystem.
+ *
+ * Most of the flags that can be set are informative only.
+ */
 typedef enum {
 	SQFS_COMP_GZIP = 1,
 	SQFS_COMP_LZMA = 2,
@@ -62,17 +200,72 @@ typedef enum {
 	SQFS_COMP_MAX = 6,
 } E_SQFS_COMPRESSOR;
 
+/**
+ * @enum E_SQFS_SUPER_FLAGS
+ *
+ * @brief Flags that can be set in @ref sqfs_super flags field.
+ */
 typedef enum {
+	/**
+	 * @brief Set to indicate that meta data blocks holding the inodes are
+	 *        stored uncompressed.
+	 */
 	SQFS_FLAG_UNCOMPRESSED_INODES = 0x0001,
+
+	/**
+	 * @brief Set to indicate that all data blocks are stored uncompressed.
+	 */
 	SQFS_FLAG_UNCOMPRESSED_DATA = 0x0002,
+
+	/**
+	 * @brief Set to indicate that all fragment blocks are stored
+	 *        uncompressed.
+	 */
 	SQFS_FLAG_UNCOMPRESSED_FRAGMENTS = 0x0008,
+
+	/**
+	 * @brief Set to indicate that there are no fragment blocks.
+	 */
 	SQFS_FLAG_NO_FRAGMENTS = 0x0010,
+
+	/**
+	 * @brief Set to indicate that fragments have been generated for all
+	 *        files that are not a multiple of the block size in size.
+	 */
 	SQFS_FLAG_ALWAYS_FRAGMENTS = 0x0020,
+
+	/**
+	 * @brief Set to indicate that data blocks have not been deduplicated.
+	 */
 	SQFS_FLAG_DUPLICATES = 0x0040,
+
+	/**
+	 * @brief Set to indicate that an NFS export table is present.
+	 */
 	SQFS_FLAG_EXPORTABLE = 0x0080,
+
+	/**
+	 * @brief Set to indicate that meta data blocks holding extended
+	 *        attributes are stored uncompressed.
+	 */
 	SQFS_FLAG_UNCOMPRESSED_XATTRS = 0x0100,
+
+	/**
+	 * @brief Set to indicate that the filesystem does not
+	 *        contain extended attributes.
+	 */
 	SQFS_FLAG_NO_XATTRS = 0x0200,
+
+	/**
+	 * @brief Set to indicate that a single, uncompressed meta data block
+	 *        with compressor options follows the super block.
+	 */
 	SQFS_FLAG_COMPRESSOR_OPTIONS = 0x0400,
+
+	/**
+	 * @brief Set to indicate that meta data blocks holding the IDs are
+	 *        stored uncompressed.
+	 */
 	SQFS_FLAG_UNCOMPRESSED_IDS = 0x0800,
 } E_SQFS_SUPER_FLAGS;
 
@@ -80,15 +273,47 @@ typedef enum {
 extern "C" {
 #endif
 
-/* Returns 0 on success. Prints error messages to stderr on failure. */
+/**
+ * @brief Initialize the SquashFS super block.
+ *
+ * @memberof sqfs_super_t
+ *
+ * @param super A pointer to a super block structure.
+ * @param block_size The uncompressed size of the data blocks in bytes.
+ * @param mtime The modification time stamp to set.
+ * @param compressor The compressor ID to set.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value if one of the
+ *         fields does not hold a valid value.
+ */
 SQFS_API int sqfs_super_init(sqfs_super_t *super, size_t block_size,
 			     uint32_t mtime,
 			     E_SQFS_COMPRESSOR compressor);
 
-/* Returns 0 on success. Prints error messages to stderr on failure. */
+/**
+ * @brief Encode and write a SquashFS super block to disk.
+ *
+ * @memberof sqfs_super_t
+ *
+ * @param super A pointer to the super block structure to write.
+ * @param file A file object through which to access the filesystem image.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value if one of the
+ *         fields does not hold a valid value.
+ */
 SQFS_API int sqfs_super_write(sqfs_super_t *super, sqfs_file_t *file);
 
-/* Returns 0 on success. Prints error messages to stderr on failure. */
+/**
+ * @brief Read a SquashFS super block from disk, decode it and check the fields
+ *
+ * @memberof sqfs_super_t
+ *
+ * @param super A pointer to the super block structure to fill.
+ * @param file A file object through which to access the filesystem image.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value if one of the
+ *         fields does not hold a valid value.
+ */
 SQFS_API int sqfs_super_read(sqfs_super_t *super, sqfs_file_t *file);
 
 #ifdef __cplusplus