chores: add documentation

include/sqsh_archive.h

@@ -73,6 +73,9 @@ const uint8_t *sqsh_trailing_data(const struct SqshTrailingContext *context);
 ////////////////////////////////////////
 // archive/superblock_context.c
 
+/**
+ * @brief The compression used in the archive.
+ */
 enum SqshSuperblockCompressionId {
 	SQSH_COMPRESSION_GZIP = 1,
 	SQSH_COMPRESSION_LZMA = 2,
@@ -82,6 +85,9 @@ enum SqshSuperblockCompressionId {
 	SQSH_COMPRESSION_ZSTD = 6,
 };
 
+/**
+ * @brief The flags used in the superblock.
+ */
 enum SqshSuperblockFlags {
 	SQSH_SUPERBLOCK_UNCOMPRESSED_INODES = 0x0001,
 	SQSH_SUPERBLOCK_UNCOMPRESSED_DATA = 0x0002,
@@ -363,6 +369,8 @@ sqsh_compression_options_new(struct SqshArchive *sqsh, int *err);
  * @brief returns the compression level of gzip
  *
  * @param[in] context the compression options context
+ *
+ * @return the compression level of gzip
  */
 uint32_t sqsh_compression_options_gzip_compression_level(
 		const struct SqshCompressionOptions *context);
@@ -371,6 +379,8 @@ uint32_t sqsh_compression_options_gzip_compression_level(
  * @brief returns the compression window size of gzip
  *
  * @param[in] context the compression options context
+ *
+ * @return the compression window size of gzip
  */
 uint16_t sqsh_compression_options_gzip_window_size(
 		const struct SqshCompressionOptions *context);
@@ -379,6 +389,8 @@ uint16_t sqsh_compression_options_gzip_window_size(
  * @brief returns the compression strategy of gzip
  *
  * @param[in] context the compression options context
+ *
+ * @return the compression strategy of gzip
  */
 enum SqshGzipStrategies sqsh_compression_options_gzip_strategies(
 		const struct SqshCompressionOptions *context);
@@ -388,6 +400,8 @@ enum SqshGzipStrategies sqsh_compression_options_gzip_strategies(
  * @brief returns the dictionary size of xz
  *
  * @param[in] context the compression options context
+ *
+ * @return the dictionary size of xz
  */
 uint32_t sqsh_compression_options_xz_dictionary_size(
 		const struct SqshCompressionOptions *context);
@@ -396,6 +410,8 @@ uint32_t sqsh_compression_options_xz_dictionary_size(
  * @brief returns the compression options of xz
  *
  * @param[in] context the compression options context
+ *
+ * @return the compression options of xz
  */
 enum SqshXzFilters sqsh_compression_options_xz_filters(
 		const struct SqshCompressionOptions *context);
@@ -405,6 +421,8 @@ enum SqshXzFilters sqsh_compression_options_xz_filters(
  * @brief returns the version of lz4 used
  *
  * @param[in] context the compression options context
+ *
+ * @return the version of lz4 used
  */
 uint32_t sqsh_compression_options_lz4_version(
 		const struct SqshCompressionOptions *context);
@@ -413,6 +431,8 @@ uint32_t sqsh_compression_options_lz4_version(
  * @brief returns the flags of lz4
  *
  * @param[in] context the compression options context
+ *
+ * @return the flags of lz4
  */
 uint32_t sqsh_compression_options_lz4_flags(
 		const struct SqshCompressionOptions *context);
@@ -422,6 +442,8 @@ uint32_t sqsh_compression_options_lz4_flags(
  * @brief returns the compression level of zstd
  *
  * @param[in] context the compression options context
+ *
+ * @return the compression level of zstd
  */
 uint32_t sqsh_compression_options_zstd_compression_level(
 		const struct SqshCompressionOptions *context);
@@ -431,6 +453,8 @@ uint32_t sqsh_compression_options_zstd_compression_level(
  * @brief returns the algorithm of lzo
  *
  * @param[in] context the compression options context
+ *
+ * @return the algorithm of lzo
  */
 enum SqshLzoAlgorithm sqsh_compression_options_lzo_algorithm(
 		const struct SqshCompressionOptions *context);
@@ -439,6 +463,8 @@ enum SqshLzoAlgorithm sqsh_compression_options_lzo_algorithm(
  * @brief returns the compression level of lzo
  *
  * @param[in] context the compression options context
+ *
+ * @return the compression level of lzo
  */
 uint32_t sqsh_compression_options_lzo_compression_level(
 		const struct SqshCompressionOptions *context);
@@ -448,6 +474,8 @@ uint32_t sqsh_compression_options_lzo_compression_level(
  * @brief Frees a SqshCompressionOptions struct.
  *
  * @param[in] context The file context to free.
+ *
+ * @return 0 on success, less than 0 on error
  */
 int sqsh_compression_options_free(struct SqshCompressionOptions *context);
 
@@ -459,13 +487,19 @@ int sqsh_compression_options_free(struct SqshCompressionOptions *context);
  * a sqsh session.
  */
 struct SqshConfig {
+/**
+ * TODO
+ */
 #define SQSH_CONFIG_FIELDS \
 	uint64_t source_size; \
 	const struct SqshMemoryMapperImpl *source_mapper; \
 	int mapper_block_size; \
 	int mapper_lru_size; \
 	int compression_lru_size;
 	SQSH_CONFIG_FIELDS
+	/**
+	 * @brief padding to ensure that the size of the struct 128 bytes.
+	 */
 	uint8_t _padding
 			[128 -
 			 offsetof(

include/sqsh_archive_private.h

@@ -47,6 +47,10 @@ extern "C" {
 ////////////////////////////////////////
 // archive/trailing_context.c
 
+/**
+ * @brief The trailing context is used to access the trailing data
+ * of the archive.
+ */
 struct SqshTrailingContext {
 	/**
 	 * @privatesection
@@ -81,6 +85,10 @@ int sqsh__trailing_cleanup(struct SqshTrailingContext *context);
 ////////////////////////////////////////
 // archive/superblock.c
 
+/**
+ * @brief The superblock context is used to access the superblock of
+ * the archive.
+ */
 struct SqshSuperblock {
 	/**
 	 * @privatesection
@@ -133,6 +141,8 @@ struct SqshCompressionOptions {
  * @brief Initialize the compression options context.
  * @param compression_options the compression options context
  * @param sqsh the Sqsh struct
+ *
+ * @return 0 on success, less than 0 on error
  */
 SQSH_NO_UNUSED int sqsh__compression_options_init(
 		struct SqshCompressionOptions *compression_options,
@@ -142,7 +152,10 @@ SQSH_NO_UNUSED int sqsh__compression_options_init(
  * @internal
  * @memberof SqshCompressionOptions
  * @brief Frees the resources used by the compression options context.
+ *
  * @param compression_options the compression options context
+ *
+ * @return 0 on success, less than 0 on error
  */
 int sqsh__compression_options_cleanup(
 		struct SqshCompressionOptions *compression_options);
@@ -175,8 +188,8 @@ struct SqshArchive {
 
 /**
  * @internal
- * @brief sqsh__init initializes the Sqsh structure.
  * @memberof SqshArchive
+ * @brief sqsh__init initializes the Sqsh structure.
  *
  * @param sqsh the Sqsh structure to initialize.
  * @param source the source to retrieve the archive from
@@ -188,19 +201,41 @@ SQSH_NO_UNUSED int sqsh__archive_init(
 		struct SqshArchive *sqsh, const void *source,
 		const struct SqshConfig *config);
 
+/**
+ * @internal
+ * @memberof SqshArchive
+ * @brief sqsh__archive_file_extract_manager retrieves a SqshExtractManager used
+ * for decompressing file contents.
+ *
+ * @param archive the SqshArchive to retrieve the SqshExtractManager from.
+ * @param file_extract_manager the SqshExtractManager to retrieve.
+ *
+ * @return 0 on success, less than 0 on error.
+ */
 int sqsh__archive_file_extract_manager(
 		struct SqshArchive *archive,
 		struct SqshExtractManager **file_extract_manager);
 
+/**
+ * @internal
+ * @memberof SqshArchive
+ * @brief sqsh__archive_fragment_extract_manager retrieves a SqshExtractManager
+ * used for decompressing fragment contents.
+ *
+ * @param archive the SqshArchive to retrieve the SqshExtractManager from.
+ * @param fragment_extract_manager the SqshExtractManager to retrieve.
+ *
+ * @return 0 on success, less than 0 on error.
+ */
 int sqsh__archive_fragment_extract_manager(
 		struct SqshArchive *archive,
-		struct SqshExtractManager **file_extract_manager);
+		struct SqshExtractManager **fragment_extract_manager);
 
 /**
  * @internal
+ * @memberof SqshArchive
  * @brief sqsh__cleanup frees all resources allocated by the Sqsh structure and
  * cleans up the structure.
- * @memberof SqshArchive
  *
  * @param sqsh the Sqsh structure to cleanup.
  * @return 0 on success, less than 0 on error.

include/sqsh_chrome_private.h

@@ -46,6 +46,9 @@ struct SqshArchive;
 ////////////////////////////////////////
 // chrome/path_resolver.c
 
+/**
+ * @brief Resolves paths to inodes.
+ */
 struct SqshPathResolver {
 	/**
 	 * @privatesection

include/sqsh_common.h

@@ -46,11 +46,22 @@ extern "C" {
 #ifdef __cplusplus
 #	define SQSH_STATIC_ASSERT(cond)
 #else
-#	define SQSH_STATIC_ASSERT(cond) _Static_assert(cond, #    cond)
+/**
+ * @brief Static assert
+ *
+ * @param cond Condition to assert
+ */
+#	define SQSH_STATIC_ASSERT(cond) _Static_assert(cond, #cond)
 #endif
 
+/**
+ * @brief Warn if return value is unused
+ */
 #define SQSH_NO_UNUSED __attribute__((warn_unused_result))
 
+/**
+ * @brief typedef used for indexing
+ */
 typedef size_t sqsh_index_t;
 
 #ifdef __cplusplus

include/sqsh_directory_private.h

@@ -44,6 +44,9 @@ extern "C" {
 ////////////////////////////////////////
 // directory/directory_iterator.c
 
+/**
+ * @brief A directory iterator.
+ */
 struct SqshDirectoryIterator {
 	/**
 	 * @privatesection

include/sqsh_error.h

@@ -42,11 +42,15 @@ extern "C" {
 
 ////////////////////////////////////////
 // error.c
-#define SQSH_ERROR_SECTION (1 << 8)
+
+/**
+ * @brief Error codes for sqsh.
+ */
 enum SqshError {
 	SQSH_SUCCESS = 0,
 	// Avoid collisions with errno
-	SQSH_ERROR_SUPERBLOCK_TOO_SMALL = SQSH_ERROR_SECTION + 1,
+	SQSH_ERROR_SECTION_START = (1 << 8),
+	SQSH_ERROR_SUPERBLOCK_TOO_SMALL,
 	SQSH_ERROR_WRONG_MAGIC,
 	SQSH_ERROR_BLOCKSIZE_MISSMATCH,
 	SQSH_ERROR_SIZE_MISSMATCH,
@@ -90,9 +94,21 @@ enum SqshError {
 	SQSH_ERROR_TODO,
 };
 
+/**
+ * @brief Print the error message for the given error code.
+ *
+ * @param error_code The error code.
+ * @param msg The message to print before the error message.
+ */
 void sqsh_perror(int error_code, const char *msg);
 
-SQSH_NO_UNUSED const char *sqsh_error_str(int errorcode);
+/**
+ * @brief Get the error message for the given error code.
+ *
+ * @param error_code The error code.
+ * @return The error message.
+ */
+SQSH_NO_UNUSED const char *sqsh_error_str(int error_code);
 
 #ifdef __cplusplus
 }