Add detailed documentation for various processing functions in AaruFormat

src/blocks/checksum.c

@@ -24,6 +24,14 @@
 #include "aaruformat.h"
 #include "log.h"
 
+/**
+ * @brief Processes a checksum block from the image stream.
+ *
+ * Reads a checksum block, parses its entries, and stores the checksums (MD5, SHA1, SHA256, SpamSum) in the context.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param entry Pointer to the index entry describing the checksum block.
+ */
 void process_checksum_block(aaruformatContext *ctx, const IndexEntry *entry)
 {
     TRACE("Entering process_checksum_block(%p, %p)", ctx, entry);

src/blocks/data.c

@@ -25,7 +25,15 @@
 #include "log.h"
 #include "uthash.h"
 
-// Process data blocks found while opening an AaruFormat file
+/**
+ * @brief Processes a data block from the image stream.
+ *
+ * Reads a data block from the image, decompresses if needed, and updates the context with its contents.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param entry Pointer to the index entry describing the data block.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t process_data_block(aaruformatContext *ctx, IndexEntry *entry)
 {
     TRACE("Entering process_data_block(%p, %p)", ctx, entry);

src/blocks/dump.c

@@ -24,6 +24,14 @@
 #include "aaruformat.h"
 #include "log.h"
 
+/**
+ * @brief Processes a dump hardware block from the image stream.
+ *
+ * Reads a dump hardware block from the image and updates the context with its contents.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param entry Pointer to the index entry describing the dump hardware block.
+ */
 void process_dumphw_block(aaruformatContext *ctx, const IndexEntry *entry)
 {
     TRACE("Entering process_dumphw_block(%p, %p)", ctx, entry);

src/blocks/metadata.c

@@ -24,7 +24,14 @@
 #include "aaruformat.h"
 #include "log.h"
 
-// Process the metadata block found while opening an AaruFormat file
+/**
+ * @brief Processes a metadata block from the image stream.
+ *
+ * Reads a metadata block from the image and updates the context with its contents.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param entry Pointer to the index entry describing the metadata block.
+ */
 void process_metadata_block(aaruformatContext *ctx, const IndexEntry *entry)
 {
     TRACE("Entering process_metadata_block(%p, %p)", ctx, entry);
@@ -231,7 +238,14 @@ void process_metadata_block(aaruformatContext *ctx, const IndexEntry *entry)
     TRACE("Exiting process_metadata_block()");
 }
 
-// Logical geometry block. It doesn't have a CRC coz, well, it's not so important
+/**
+ * @brief Processes a logical geometry block from the image stream.
+ *
+ * Reads a logical geometry block from the image and updates the context with its contents.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param entry Pointer to the index entry describing the geometry block.
+ */
 void process_geometry_block(aaruformatContext *ctx, const IndexEntry *entry)
 {
     TRACE("Entering process_geometry_block(%p, %p)", ctx, entry);
@@ -284,7 +298,14 @@ void process_geometry_block(aaruformatContext *ctx, const IndexEntry *entry)
     TRACE("Exiting process_geometry_block()");
 }
 
-// CICM XML metadata block
+/**
+ * @brief Processes a CICM XML metadata block from the image stream.
+ *
+ * Reads a CICM XML metadata block from the image and updates the context with its contents.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param entry Pointer to the index entry describing the CICM block.
+ */
 void process_cicm_block(aaruformatContext *ctx, const IndexEntry *entry)
 {
     TRACE("Entering process_cicm_block(%p, %p)", ctx, entry);

src/blocks/optical.c

@@ -24,6 +24,14 @@
 #include "aaruformat.h"
 #include "log.h"
 
+/**
+ * @brief Processes a tracks block from the image stream.
+ *
+ * Reads a tracks block from the image and updates the context with its contents.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param entry Pointer to the index entry describing the tracks block.
+ */
 void process_tracks_block(aaruformatContext *ctx, const IndexEntry *entry)
 {
     int      pos       = 0;

src/checksum/ecc_cd.c

@@ -25,6 +25,13 @@
 #include "aaruformat.h"
 #include "log.h"
 
+/**
+ * @brief Initializes a Compact Disc ECC context.
+ *
+ * Allocates and initializes a context for Compact Disc ECC calculations.
+ *
+ * @return Pointer to the initialized CdEccContext structure, or NULL on failure.
+ */
 void *aaruf_ecc_cd_init()
 {
     TRACE("Entering aaruf_ecc_cd_init()");
@@ -84,6 +91,13 @@ void *aaruf_ecc_cd_init()
     return context;
 }
 
+/**
+ * @brief Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 1).
+ *
+ * @param context Pointer to the ECC context.
+ * @param sector Pointer to the sector data.
+ * @return true if the suffix is correct, false otherwise.
+ */
 bool aaruf_ecc_cd_is_suffix_correct(void *context, const uint8_t *sector)
 {
     TRACE("Entering aaruf_ecc_cd_is_suffix_correct(%p, %p)", context, sector);
@@ -138,6 +152,13 @@ bool aaruf_ecc_cd_is_suffix_correct(void *context, const uint8_t *sector)
     return calculatedEdc == storedEdc;
 }
 
+/**
+ * @brief Checks if the suffix (EDC/ECC) of a CD sector is correct (Mode 2).
+ *
+ * @param context Pointer to the ECC context.
+ * @param sector Pointer to the sector data.
+ * @return true if the suffix is correct, false otherwise.
+ */
 bool aaruf_ecc_cd_is_suffix_correct_mode2(void *context, const uint8_t *sector)
 {
     TRACE("Entering aaruf_ecc_cd_is_suffix_correct_mode2(%p, %p)", context, sector);
@@ -185,6 +206,22 @@ bool aaruf_ecc_cd_is_suffix_correct_mode2(void *context, const uint8_t *sector)
     return calculatedEdc == storedEdc;
 }
 
+/**
+ * @brief Checks the ECC of a CD sector.
+ *
+ * @param context Pointer to the ECC context.
+ * @param address Pointer to the address field.
+ * @param data Pointer to the data field.
+ * @param majorCount Number of major iterations.
+ * @param minorCount Number of minor iterations.
+ * @param majorMult Major multiplier.
+ * @param minorInc Minor increment.
+ * @param ecc Pointer to the ECC field.
+ * @param addressOffset Offset for the address field.
+ * @param dataOffset Offset for the data field.
+ * @param eccOffset Offset for the ECC field.
+ * @return true if ECC is correct, false otherwise.
+ */
 bool aaruf_ecc_cd_check(void *context, const uint8_t *address, const uint8_t *data, uint32_t majorCount,
                         uint32_t minorCount, uint32_t majorMult, uint32_t minorInc, const uint8_t *ecc,
                         int32_t addressOffset, int32_t dataOffset, int32_t eccOffset)
@@ -238,6 +275,21 @@ bool aaruf_ecc_cd_check(void *context, const uint8_t *address, const uint8_t *da
     return true;
 }
 
+/**
+ * @brief Writes ECC for a CD sector.
+ *
+ * @param context Pointer to the ECC context.
+ * @param address Pointer to the address field.
+ * @param data Pointer to the data field.
+ * @param majorCount Number of major iterations.
+ * @param minorCount Number of minor iterations.
+ * @param majorMult Major multiplier.
+ * @param minorInc Minor increment.
+ * @param ecc Pointer to the ECC field to write.
+ * @param addressOffset Offset for the address field.
+ * @param dataOffset Offset for the data field.
+ * @param eccOffset Offset for the ECC field.
+ */
 void aaruf_ecc_cd_write(void *context, const uint8_t *address, const uint8_t *data, uint32_t majorCount,
                         uint32_t minorCount, uint32_t majorMult, uint32_t minorInc, uint8_t *ecc, int32_t addressOffset,
                         int32_t dataOffset, int32_t eccOffset)
@@ -288,6 +340,17 @@ void aaruf_ecc_cd_write(void *context, const uint8_t *address, const uint8_t *da
     TRACE("Exiting aaruf_ecc_cd_write()");
 }
 
+/**
+ * @brief Writes ECC for a full CD sector (both P and Q ECC).
+ *
+ * @param context Pointer to the ECC context.
+ * @param address Pointer to the address field.
+ * @param data Pointer to the data field.
+ * @param ecc Pointer to the ECC field to write.
+ * @param addressOffset Offset for the address field.
+ * @param dataOffset Offset for the data field.
+ * @param eccOffset Offset for the ECC field.
+ */
 void aaruf_ecc_cd_write_sector(void *context, const uint8_t *address, const uint8_t *data, uint8_t *ecc,
                                int32_t addressOffset, int32_t dataOffset, int32_t eccOffset)
 {
@@ -300,6 +363,14 @@ void aaruf_ecc_cd_write_sector(void *context, const uint8_t *address, const uint
     TRACE("Exiting aaruf_ecc_cd_write_sector()");
 }
 
+/**
+ * @brief Converts a CD LBA (Logical Block Address) to MSF (Minute:Second:Frame) format.
+ *
+ * @param pos LBA position.
+ * @param minute Pointer to store the minute value.
+ * @param second Pointer to store the second value.
+ * @param frame Pointer to store the frame value.
+ */
 void aaruf_cd_lba_to_msf(int64_t pos, uint8_t *minute, uint8_t *second, uint8_t *frame)
 {
     TRACE("Entering aaruf_cd_lba_to_msf(%lld, %p, %p, %p)", pos, minute, second, frame);
@@ -311,8 +382,14 @@ void aaruf_cd_lba_to_msf(int64_t pos, uint8_t *minute, uint8_t *second, uint8_t
     TRACE("Exiting aaruf_cd_lba_to_msf() = %u:%u:%u", *minute, *second, *frame);
 }
 
-void aaruf_ecc_cd_reconstruct_prefix(uint8_t *sector,  // must point to a full 2352-byte sector
+/**
-                                     uint8_t type, int64_t lba)
+ * @brief Reconstructs the prefix (sync, address, mode) of a CD sector.
+ *
+ * @param sector Pointer to the sector data (must be 2352 bytes).
+ * @param type Track type (mode).
+ * @param lba Logical Block Address.
+ */
+void aaruf_ecc_cd_reconstruct_prefix(uint8_t *sector, uint8_t type, int64_t lba)
 {
     TRACE("Entering aaruf_ecc_cd_reconstruct_prefix(%p, %u, %lld)", sector, type, lba);
 
@@ -372,9 +449,14 @@ void aaruf_ecc_cd_reconstruct_prefix(uint8_t *sector,  // must point to a full 2
     TRACE("Exiting aaruf_ecc_cd_reconstruct_prefix()");
 }
 
-void aaruf_ecc_cd_reconstruct(void    *context,
+/**
-                              uint8_t *sector,  // must point to a full 2352-byte sector
+ * @brief Reconstructs the EDC and ECC fields of a CD sector.
-                              uint8_t  type)
+ *
+ * @param context Pointer to the ECC context.
+ * @param sector Pointer to the sector data (must be 2352 bytes).
+ * @param type Track type (mode).
+ */
+void aaruf_ecc_cd_reconstruct(void *context, uint8_t *sector, uint8_t type)
 {
     TRACE("Entering aaruf_ecc_cd_reconstruct(%p, %p, %u)", context, sector, type);
 
@@ -454,6 +536,16 @@ void aaruf_ecc_cd_reconstruct(void    *context,
     TRACE("Exiting aaruf_ecc_cd_reconstruct()");
 }
 
+/**
+ * @brief Computes the EDC (Error Detection Code) for a CD sector.
+ *
+ * @param context Pointer to the ECC context.
+ * @param edc Initial EDC value.
+ * @param src Pointer to the data to compute EDC over.
+ * @param size Number of bytes to process.
+ * @param pos Starting position in the data.
+ * @return Computed EDC value.
+ */
 uint32_t aaruf_edc_cd_compute(void *context, uint32_t edc, const uint8_t *src, int size, int pos)
 {
     TRACE("Entering aaruf_edc_cd_compute(%p, %u, %p, %d, %d)", context, edc, src, size, pos);

src/checksum/simd.c

@@ -36,6 +36,17 @@
 
 #endif
 
+/**
+ * @brief Executes the CPUID instruction to retrieve CPU information.
+ *
+ * Retrieves information about the CPU based on the specified info code.
+ *
+ * @param info The information code to query.
+ * @param eax Pointer to store the EAX register result.
+ * @param ebx Pointer to store the EBX register result.
+ * @param ecx Pointer to store the ECX register result.
+ * @param edx Pointer to store the EDX register result.
+ */
 static void cpuid(int info, unsigned *eax, unsigned *ebx, unsigned *ecx, unsigned *edx)
 {
     TRACE("Entering cpuid(%d, %d, %d, %d, %d)", info, *eax, *ebx, *ecx, *edx);
@@ -63,6 +74,16 @@ static void cpuid(int info, unsigned *eax, unsigned *ebx, unsigned *ecx, unsigne
     TRACE("Exiting cpuid(%d, %d, %d, %d, %d)", info, *eax, *ebx, *ecx, *edx);
 }
 
+/**
+ * @brief Executes the CPUID instruction with the given info and count.
+ *
+ * @param info CPUID info code.
+ * @param count CPUID count code.
+ * @param eax Pointer to store EAX result.
+ * @param ebx Pointer to store EBX result.
+ * @param ecx Pointer to store ECX result.
+ * @param edx Pointer to store EDX result.
+ */
 static void cpuidex(int info, int count, unsigned *eax, unsigned *ebx, unsigned *ecx, unsigned *edx)
 {
     TRACE("Entering cpuidex(%d, %d, %d, %d, %d, %d)", info, count, *eax, *ebx, *ecx, *edx);
@@ -90,6 +111,11 @@ static void cpuidex(int info, int count, unsigned *eax, unsigned *ebx, unsigned
     TRACE("Exiting cpuidex(%d, %d, %d, %d, %d, %d)", info, count, *eax, *ebx, *ecx, *edx);
 }
 
+/**
+ * @brief Checks if the CPU supports PCLMULQDQ (carry-less multiplication) and SSE4.1.
+ *
+ * @return Non-zero if supported, zero otherwise.
+ */
 int have_clmul()
 {
     TRACE("Entering have_clmul()");
@@ -106,6 +132,11 @@ int have_clmul()
     return has_pclmulqdq && has_sse41;
 }
 
+/**
+ * @brief Checks if the CPU supports SSSE3 instructions.
+ *
+ * @return Non-zero if supported, zero otherwise.
+ */
 int have_ssse3()
 {
     TRACE("Entering have_ssse3()");
@@ -116,6 +147,11 @@ int have_ssse3()
     return ecx & 0x200;
 }
 
+/**
+ * @brief Checks if the CPU supports AVX2 instructions.
+ *
+ * @return Non-zero if supported, zero otherwise.
+ */
 int have_avx2()
 {
     TRACE("Entering have_avx2()");
@@ -140,6 +176,11 @@ int have_avx2()
 #endif
 
 #if (defined(__aarch64__) || defined(_M_ARM64) || defined(__arm__) || defined(_M_ARM)) && defined(__APPLE__)
+/**
+ * @brief Checks if the CPU supports NEON instructions on Apple platforms.
+ *
+ * @return Non-zero if supported, zero otherwise.
+ */
 int have_neon_apple()
 {
     TRACE("Entering have_neon_apple()");
@@ -157,6 +198,11 @@ int have_neon_apple()
     return value == 1;
 }
 
+/**
+ * @brief Checks if the CPU supports CRC32 instructions on Apple platforms.
+ *
+ * @return Non-zero if supported, zero otherwise.
+ */
 int have_crc32_apple()
 {
     TRACE("Entering have_crc32_apple()");
@@ -174,6 +220,11 @@ int have_crc32_apple()
     return value == 1;
 }
 
+/**
+ * @brief Checks if the CPU supports cryptographic instructions on Apple platforms.
+ *
+ * @return Non-zero if supported, zero otherwise.
+ */
 int have_crypto_apple() { return 0; }
 #endif
 

src/checksum/spamsum.c

@@ -48,6 +48,14 @@ AARU_EXPORT spamsum_ctx *AARU_CALL aaruf_spamsum_init(void)
     return ctx;
 }
 
+/**
+ * @brief Updates the spamsum context with new data.
+ *
+ * @param ctx Pointer to the spamsum context.
+ * @param data Pointer to the data to process.
+ * @param len Length of the data in bytes.
+ * @return 0 on success, -1 on error.
+ */
 AARU_EXPORT int AARU_CALL aaruf_spamsum_update(spamsum_ctx *ctx, const uint8_t *data, uint32_t len)
 {
     if(!ctx || !data) return -1;
@@ -59,6 +67,11 @@ AARU_EXPORT int AARU_CALL aaruf_spamsum_update(spamsum_ctx *ctx, const uint8_t *
     return 0;
 }
 
+/**
+ * @brief Frees a spamsum (fuzzy hash) context.
+ *
+ * @param ctx Pointer to the spamsum context to free.
+ */
 AARU_EXPORT void AARU_CALL aaruf_spamsum_free(spamsum_ctx *ctx)
 {
     if(ctx) free(ctx);

src/close.c

@@ -29,6 +29,14 @@
 #include "internal.h"
 #include "log.h"
 
+/**
+ * @brief Closes an AaruFormat image context and frees resources.
+ *
+ * Closes the image file, frees memory, and releases all resources associated with the context.
+ *
+ * @param context Pointer to the aaruformat context to close.
+ * @return 0 on success, or -1 on error.
+ */
 int aaruf_close(void *context)
 {
     TRACE("Entering aaruf_close(%p)", context);

src/compression/cst.c

@@ -22,6 +22,16 @@
 
 #include "aaruformat.h"
 
+/**
+ * @brief Transforms interleaved subchannel data to sequential format.
+ *
+ * Converts interleaved subchannel data into a sequential format for further processing.
+ *
+ * @param interleaved Pointer to the interleaved data buffer.
+ * @param sequential Pointer to the output sequential data buffer.
+ * @param length Length of the data buffer.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t aaruf_cst_transform(const uint8_t *interleaved, uint8_t *sequential, size_t length)
 {
     uint8_t *p = NULL;
@@ -172,6 +182,14 @@ int32_t aaruf_cst_transform(const uint8_t *interleaved, uint8_t *sequential, siz
     return AARUF_STATUS_OK;
 }
 
+/**
+ * @brief Reverses the CST (Claunia's Subchannel Transform) transformation from sequential to interleaved data.
+ *
+ * @param sequential Pointer to the sequential data buffer.
+ * @param interleaved Pointer to the output buffer for interleaved data.
+ * @param length Length of the data in bytes.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t aaruf_cst_untransform(const uint8_t *sequential, uint8_t *interleaved, size_t length)
 {
     uint8_t *p, *q, *r, *s, *t, *u, *v, *w;

src/compression/flac.c

@@ -34,6 +34,17 @@ static FLAC__StreamDecoderWriteStatus write_callback(const FLAC__StreamDecoder *
 static void error_callback(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status,
                            void *client_data);
 
+/**
+ * @brief Decodes a FLAC-compressed Red Book audio buffer.
+ *
+ * Decompresses FLAC-compressed Red Book audio data into the destination buffer.
+ *
+ * @param dst_buffer Pointer to the destination buffer.
+ * @param dst_size Size of the destination buffer.
+ * @param src_buffer Pointer to the source (compressed) buffer.
+ * @param src_size Size of the source buffer.
+ * @return Number of bytes written to the destination buffer.
+ */
 AARU_EXPORT size_t AARU_CALL aaruf_flac_decode_redbook_buffer(uint8_t *dst_buffer, size_t dst_size,
                                                               const uint8_t *src_buffer, size_t src_size)
 {
@@ -141,6 +152,27 @@ static FLAC__StreamEncoderWriteStatus encoder_write_callback(const FLAC__StreamE
                                                              const FLAC__byte buffer[], size_t bytes, uint32_t samples,
                                                              uint32_t current_frame, void *client_data);
 
+/**
+ * @brief Encodes a Red Book audio buffer to FLAC format.
+ *
+ * @param dst_buffer Pointer to the destination buffer for FLAC data.
+ * @param dst_size Size of the destination buffer in bytes.
+ * @param src_buffer Pointer to the source Red Book audio buffer.
+ * @param src_size Size of the source buffer in bytes.
+ * @param blocksize FLAC block size.
+ * @param do_mid_side_stereo Enable mid-side stereo encoding.
+ * @param loose_mid_side_stereo Enable loose mid-side stereo encoding.
+ * @param apodization Apodization string for FLAC encoder.
+ * @param max_lpc_order Maximum LPC order.
+ * @param qlp_coeff_precision QLP coefficient precision.
+ * @param do_qlp_coeff_prec_search Enable QLP coefficient precision search.
+ * @param do_exhaustive_model_search Enable exhaustive model search.
+ * @param min_residual_partition_order Minimum residual partition order.
+ * @param max_residual_partition_order Maximum residual partition order.
+ * @param application_id Application ID string for FLAC encoder.
+ * @param application_id_len Length of the application ID string.
+ * @return Number of bytes written to the destination buffer.
+ */
 AARU_EXPORT size_t AARU_CALL aaruf_flac_encode_redbook_buffer(
     uint8_t *dst_buffer, size_t dst_size, const uint8_t *src_buffer, size_t src_size, uint32_t blocksize,
     int32_t do_mid_side_stereo, int32_t loose_mid_side_stereo, const char *apodization, uint32_t max_lpc_order,

src/compression/lzma.c

@@ -23,12 +23,45 @@
 
 #include "../../3rdparty/lzma-21.03beta/C/LzmaLib.h"
 
+/**
+ * @brief Decodes an LZMA-compressed buffer.
+ *
+ * Decompresses data from the source buffer into the destination buffer using LZMA.
+ *
+ * @param dst_buffer Pointer to the destination buffer.
+ * @param dst_size Pointer to the size of the destination buffer; updated with the actual size.
+ * @param src_buffer Pointer to the source (compressed) buffer.
+ * @param srcLen Pointer to the size of the source buffer; updated with the actual size read.
+ * @param props Pointer to the LZMA properties.
+ * @param propsSize Size of the LZMA properties.
+ * @return 0 on success, or an error code on failure.
+ */
 AARU_EXPORT int32_t AARU_CALL aaruf_lzma_decode_buffer(uint8_t *dst_buffer, size_t *dst_size, const uint8_t *src_buffer,
                                                        size_t *srcLen, const uint8_t *props, size_t propsSize)
 {
     return LzmaUncompress(dst_buffer, dst_size, src_buffer, srcLen, props, propsSize);
 }
 
+/**
+ * @brief Encodes a buffer using LZMA compression.
+ *
+ * Compresses data from the source buffer into the destination buffer using LZMA.
+ *
+ * @param dst_buffer Pointer to the destination buffer.
+ * @param dst_size Pointer to the size of the destination buffer; updated with the actual size.
+ * @param src_buffer Pointer to the source (uncompressed) buffer.
+ * @param srcLen Size of the source buffer.
+ * @param outProps Pointer to the output LZMA properties.
+ * @param outPropsSize Pointer to the size of the output LZMA properties.
+ * @param level Compression level.
+ * @param dictSize Dictionary size.
+ * @param lc LZMA literal context bits.
+ * @param lp LZMA literal position bits.
+ * @param pb LZMA position bits.
+ * @param fb Number of fast bytes.
+ * @param numThreads Number of threads to use.
+ * @return 0 on success, or an error code on failure.
+ */
 AARU_EXPORT int32_t AARU_CALL aaruf_lzma_encode_buffer(uint8_t *dst_buffer, size_t *dst_size, const uint8_t *src_buffer,
                                                        size_t srcLen, uint8_t *outProps, size_t *outPropsSize,
                                                        int32_t level, uint32_t dictSize, int32_t lc, int32_t lp,

src/crc64/crc64.c

@@ -22,6 +22,13 @@
 
 #include "log.h"
 
+/**
+ * @brief Initializes a CRC64 context.
+ *
+ * Allocates and initializes a CRC64 context for checksum calculations.
+ *
+ * @return Pointer to the initialized crc64_ctx structure, or NULL on failure.
+ */
 AARU_EXPORT crc64_ctx *AARU_CALL aaruf_crc64_init(void)
 {
     TRACE("Entering aaruf_crc64_init()");
@@ -35,6 +42,16 @@ AARU_EXPORT crc64_ctx *AARU_CALL aaruf_crc64_init(void)
     return ctx;
 }
 
+/**
+ * @brief Updates the CRC64 context with new data.
+ *
+ * Processes the given data buffer and updates the CRC64 value in the context.
+ *
+ * @param ctx Pointer to the CRC64 context.
+ * @param data Pointer to the data buffer.
+ * @param len Length of the data buffer.
+ * @return 0 on success, or -1 on error.
+ */
 AARU_EXPORT int AARU_CALL aaruf_crc64_update(crc64_ctx *ctx, const uint8_t *data, uint32_t len)
 {
     TRACE("Entering aaruf_crc64_update(%p, %p, %u)", ctx, data, len);
@@ -75,6 +92,13 @@ AARU_EXPORT int AARU_CALL aaruf_crc64_update(crc64_ctx *ctx, const uint8_t *data
     return 0;
 }
 
+/**
+ * @brief Updates a CRC64 value using the slicing-by-8 algorithm.
+ *
+ * @param previous_crc Pointer to the previous CRC64 value (input/output).
+ * @param data Pointer to the data buffer.
+ * @param len Length of the data buffer in bytes.
+ */
 AARU_EXPORT void AARU_CALL aaruf_crc64_slicing(uint64_t *previous_crc, const uint8_t *data, uint32_t len)
 {
     uint64_t c = *previous_crc;
@@ -107,6 +131,13 @@ AARU_EXPORT void AARU_CALL aaruf_crc64_slicing(uint64_t *previous_crc, const uin
     *previous_crc = c;
 }
 
+/**
+ * @brief Computes the final CRC64 value from the context.
+ *
+ * @param ctx Pointer to the CRC64 context.
+ * @param crc Pointer to store the resulting CRC64 value.
+ * @return 0 on success, -1 on error.
+ */
 AARU_EXPORT int AARU_CALL aaruf_crc64_final(crc64_ctx *ctx, uint64_t *crc)
 {
     if(!ctx) return -1;
@@ -116,6 +147,11 @@ AARU_EXPORT int AARU_CALL aaruf_crc64_final(crc64_ctx *ctx, uint64_t *crc)
     return 0;
 }
 
+/**
+ * @brief Frees a CRC64 context.
+ *
+ * @param ctx Pointer to the CRC64 context to free.
+ */
 AARU_EXPORT void AARU_CALL aaruf_crc64_free(crc64_ctx *ctx)
 {
     if(ctx) free(ctx);

src/crc64/crc64_clmul.c

@@ -82,6 +82,14 @@ CLMUL static __m128i fold(__m128i in, __m128i foldConstants)
     return _mm_xor_si128(_mm_clmulepi64_si128(in, foldConstants, 0x00), _mm_clmulepi64_si128(in, foldConstants, 0x11));
 }
 
+/**
+ * @brief Computes CRC64 using the CLMUL (carry-less multiplication) instruction set.
+ *
+ * @param crc Initial CRC64 value.
+ * @param data Pointer to the data buffer.
+ * @param length Length of the data buffer in bytes.
+ * @return Computed CRC64 value.
+ */
 AARU_EXPORT CLMUL uint64_t AARU_CALL aaruf_crc64_clmul(uint64_t crc, const uint8_t *data, long length)
 {
     TRACE("Entering aaruf_crc64_clmul(%" PRIu64 ", %p, %ld)", crc, data, length);

src/crc64/crc64_vmull.c

@@ -49,6 +49,14 @@ TARGET_WITH_SIMD FORCE_INLINE uint64x2_t fold(uint64x2_t in, uint64x2_t foldCons
                      sse2neon_vmull_p64(vget_high_u64(in), vget_high_u64(foldConstants)));
 }
 
+/**
+ * @brief Computes CRC64 using the ARM NEON VMULL instruction set.
+ *
+ * @param previous_crc Initial CRC64 value.
+ * @param data Pointer to the data buffer.
+ * @param len Length of the data buffer in bytes.
+ * @return Computed CRC64 value.
+ */
 AARU_EXPORT TARGET_WITH_SIMD uint64_t AARU_CALL aaruf_crc64_vmull(uint64_t previous_crc, const uint8_t *data, long len)
 {
     TRACE("Entering aaruf_crc64_vmull(%llu, %p, %ld)", previous_crc, data, len);

src/create.c

@@ -26,6 +26,24 @@
 #include "internal.h"
 #include "log.h"
 
+/**
+ * @brief Creates a new AaruFormat image file.
+ *
+ * Allocates and initializes a new aaruformat context and image file with the specified parameters.
+ *
+ * @param filepath Path to the image file to create.
+ * @param mediaType Media type identifier.
+ * @param sectorSize Size of each sector in bytes.
+ * @param userSectors Number of user data sectors.
+ * @param negativeSectors Number of negative sectors.
+ * @param overflowSectors Number of overflow sectors.
+ * @param options String with creation options.
+ * @param applicationName Pointer to the application name string.
+ * @param applicationNameLength Length of the application name string.
+ * @param applicationMajorVersion Major version of the application.
+ * @param applicationMinorVersion Minor version of the application.
+ * @return Pointer to the created aaruformat context, or NULL on failure.
+ */
 void *aaruf_create(const char *filepath, uint32_t mediaType, uint32_t sectorSize, uint64_t userSectors,
                    uint64_t negativeSectors, uint64_t overflowSectors, const char *options,
                    const uint8_t *applicationName, uint8_t applicationNameLength, uint8_t applicationMajorVersion,

src/ddt/ddt_v1.c

@@ -28,6 +28,16 @@
 #include "aaruformat.h"
 #include "log.h"
 
+/**
+ * @brief Processes a DDT v1 block from the image stream.
+ *
+ * Reads and decompresses (if needed) a DDT v1 block, verifies its integrity, and loads it into memory or maps it.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param entry Pointer to the index entry describing the DDT block.
+ * @param foundUserDataDdt Pointer to a boolean that will be set to true if a user data DDT was found and loaded.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t process_ddt_v1(aaruformatContext *ctx, IndexEntry *entry, bool *foundUserDataDdt)
 {
     TRACE("Entering process_ddt_v1(%p, %p, %d)", ctx, entry, *foundUserDataDdt);
@@ -288,6 +298,18 @@ int32_t process_ddt_v1(aaruformatContext *ctx, IndexEntry *entry, bool *foundUse
     return AARUF_STATUS_OK;
 }
 
+/**
+ * @brief Decodes a DDT v1 entry for a given sector address.
+ *
+ * Determines the offset and block offset for a sector using the DDT v1 table.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param sectorAddress Logical sector address to decode.
+ * @param offset Pointer to store the resulting offset.
+ * @param blockOffset Pointer to store the resulting block offset.
+ * @param sectorStatus Pointer to store the sector status.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t decode_ddt_entry_v1(aaruformatContext *ctx, uint64_t sectorAddress, uint64_t *offset, uint64_t *blockOffset,
                             uint8_t *sectorStatus)
 {

src/ddt/ddt_v2.c

@@ -25,6 +25,16 @@
 #include "internal.h"
 #include "log.h"
 
+/**
+ * @brief Processes a DDT v2 block from the image stream.
+ *
+ * Reads and decompresses (if needed) a DDT v2 block, verifies its CRC, and loads it into memory.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param entry Pointer to the index entry describing the DDT block.
+ * @param foundUserDataDdt Pointer to a boolean that will be set to true if a user data DDT was found and loaded.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t process_ddt_v2(aaruformatContext *ctx, IndexEntry *entry, bool *foundUserDataDdt)
 {
     TRACE("Entering process_ddt_v2(%p, %p, %d)", ctx, entry, *foundUserDataDdt);
@@ -405,6 +415,18 @@ int32_t process_ddt_v2(aaruformatContext *ctx, IndexEntry *entry, bool *foundUse
     return AARUF_STATUS_OK;
 }
 
+/**
+ * @brief Decodes a DDT v2 entry for a given sector address.
+ *
+ * Determines the offset and block offset for a sector using the DDT v2 table(s).
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param sectorAddress Logical sector address to decode.
+ * @param offset Pointer to store the resulting offset.
+ * @param blockOffset Pointer to store the resulting block offset.
+ * @param sectorStatus Pointer to store the sector status.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t decode_ddt_entry_v2(aaruformatContext *ctx, uint64_t sectorAddress, uint64_t *offset, uint64_t *blockOffset,
                             uint8_t *sectorStatus)
 {
@@ -425,6 +447,18 @@ int32_t decode_ddt_entry_v2(aaruformatContext *ctx, uint64_t sectorAddress, uint
     return decode_ddt_single_level_v2(ctx, sectorAddress, offset, blockOffset, sectorStatus);
 }
 
+/**
+ * @brief Decodes a single-level DDT v2 entry for a given sector address.
+ *
+ * Used when the DDT table does not use multi-level indirection.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param sectorAddress Logical sector address to decode.
+ * @param offset Pointer to store the resulting offset.
+ * @param blockOffset Pointer to store the resulting block offset.
+ * @param sectorStatus Pointer to store the sector status.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t decode_ddt_single_level_v2(aaruformatContext *ctx, uint64_t sectorAddress, uint64_t *offset,
                                    uint64_t *blockOffset, uint8_t *sectorStatus)
 {
@@ -494,6 +528,18 @@ int32_t decode_ddt_single_level_v2(aaruformatContext *ctx, uint64_t sectorAddres
     return AARUF_STATUS_OK;
 }
 
+/**
+ * @brief Decodes a multi-level DDT v2 entry for a given sector address.
+ *
+ * Used when the DDT table uses multi-level indirection (tableShift > 0).
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param sectorAddress Logical sector address to decode.
+ * @param offset Pointer to store the resulting offset.
+ * @param blockOffset Pointer to store the resulting block offset.
+ * @param sectorStatus Pointer to store the sector status.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t decode_ddt_multi_level_v2(aaruformatContext *ctx, uint64_t sectorAddress, uint64_t *offset,
                                   uint64_t *blockOffset, uint8_t *sectorStatus)
 {
@@ -758,6 +804,17 @@ int32_t decode_ddt_multi_level_v2(aaruformatContext *ctx, uint64_t sectorAddress
     return AARUF_STATUS_OK;
 }
 
+/**
+ * @brief Sets a DDT v2 entry for a given sector address.
+ *
+ * Updates the DDT v2 table(s) with the specified offset, block offset, and sector status for a sector.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param sectorAddress Logical sector address to set.
+ * @param offset Offset to set for the sector.
+ * @param blockOffset Block offset to set for the sector.
+ * @param sectorStatus Status to set for the sector.
+ */
 void set_ddt_entry_v2(aaruformatContext *ctx, uint64_t sectorAddress, uint64_t offset, uint64_t blockOffset,
                       uint8_t sectorStatus)
 {
@@ -777,6 +834,18 @@ void set_ddt_entry_v2(aaruformatContext *ctx, uint64_t sectorAddress, uint64_t o
         set_ddt_single_level_v2(ctx, sectorAddress, false, offset, blockOffset, sectorStatus);
 }
 
+/**
+ * @brief Sets a single-level DDT v2 entry for a given sector address.
+ *
+ * Used when the DDT table does not use multi-level indirection.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param sectorAddress Logical sector address to set.
+ * @param negative Indicates if the sector address is negative.
+ * @param offset Offset to set for the sector.
+ * @param blockOffset Block offset to set for the sector.
+ * @param sectorStatus Status to set for the sector.
+ */
 void set_ddt_single_level_v2(aaruformatContext *ctx, uint64_t sectorAddress, bool negative, uint64_t offset,
                              uint64_t blockOffset, uint8_t sectorStatus)
 {
@@ -835,6 +904,18 @@ void set_ddt_single_level_v2(aaruformatContext *ctx, uint64_t sectorAddress, boo
     }
 }
 
+/**
+ * @brief Sets a multi-level DDT v2 entry for a given sector address.
+ *
+ * Used when the DDT table uses multi-level indirection (tableShift > 0).
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param sectorAddress Logical sector address to set.
+ * @param negative Indicates if the sector address is negative.
+ * @param offset Offset to set for the sector.
+ * @param blockOffset Block offset to set for the sector.
+ * @param sectorStatus Status to set for the sector.
+ */
 void set_ddt_multi_level_v2(aaruformatContext *ctx, uint64_t sectorAddress, bool negative, uint64_t offset,
                             uint64_t blockOffset, uint8_t sectorStatus)
 {

src/helpers.c

@@ -20,7 +20,14 @@
 
 #include <aaruformat.h>
 
-// Converts between image data type and aaru media tag type
+/**
+ * @brief Converts an image data type to an Aaru media tag type.
+ *
+ * Maps the given image data type to the corresponding Aaru media tag type.
+ *
+ * @param type Image data type identifier.
+ * @return Corresponding Aaru media tag type, or -1 if not found.
+ */
 int32_t aaruf_get_media_tag_type_for_datatype(int32_t type)
 {
     switch(type)

src/identify.c

@@ -21,12 +21,13 @@
 
 #include <aaruformat.h>
 
-//! Identifies a file as aaruformat, using path
+/**
-/*!
+ * @brief Identifies a file as an AaruFormat image using a file path.
  *
- * @param filename path to the file to aaruf_identify
+ * Opens the file at the given path and determines if it is an AaruFormat image.
- * @return If positive, confidence value, with 100 being maximum confidentiality, and 0 not recognizing the file.
+ *
- * If negative, error value
+ * @param filename Path to the file to identify.
+ * @return If positive, confidence value (100 = maximum confidence, 0 = not recognized). If negative, error value.
  */
 int aaruf_identify(const char *filename)
 {
@@ -43,12 +44,13 @@ int aaruf_identify(const char *filename)
     return ret;
 }
 
-//! Identifies a file as aaruformat, using an already existing stream
+/**
-/*!
+ * @brief Identifies a file as an AaruFormat image using an open stream.
  *
- * @param imageStream stream of the file to aaruf_identify
+ * Determines if the provided stream is an AaruFormat image.
- * @return If positive, confidence value, with 100 being maximum confidentiality, and 0 not recognizing the file.
+ *
- * If negative, error value
+ * @param imageStream Stream of the file to identify.
+ * @return If positive, confidence value (100 = maximum confidence, 0 = not recognized). If negative, error value.
  */
 int aaruf_identify_stream(FILE *imageStream)
 {

src/index/index_v1.c

@@ -24,6 +24,14 @@
 #include "log.h"
 #include "utarray.h"
 
+/**
+ * @brief Processes an index block (version 1) from the image stream.
+ *
+ * Reads and parses an index block (version 1) from the image, returning an array of index entries.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @return Pointer to a UT_array of IndexEntry structures, or NULL on failure.
+ */
 UT_array *process_index_v1(aaruformatContext *ctx)
 {
     TRACE("Entering process_index_v1(%p)", ctx);
@@ -64,6 +72,14 @@ UT_array *process_index_v1(aaruformatContext *ctx)
     return index_entries;
 }
 
+/**
+ * @brief Verifies the integrity of an index block (version 1) in the image stream.
+ *
+ * Checks the CRC64 of the index block without decompressing it.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @return Status code (AARUF_STATUS_OK on success, or an error code).
+ */
 int32_t verify_index_v1(aaruformatContext *ctx)
 {
     TRACE("Entering verify_index_v1(%p)", ctx);

src/index/index_v2.c

@@ -24,6 +24,14 @@
 #include "log.h"
 #include "utarray.h"
 
+/**
+ * @brief Processes an index block (version 2) from the image stream.
+ *
+ * Reads and parses an index block (version 2) from the image, returning an array of index entries.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @return Pointer to a UT_array of IndexEntry structures, or NULL on failure.
+ */
 UT_array *process_index_v2(aaruformatContext *ctx)
 {
     TRACE("Entering process_index_v2(%p)", ctx);
@@ -64,6 +72,14 @@ UT_array *process_index_v2(aaruformatContext *ctx)
     return index_entries;
 }
 
+/**
+ * @brief Verifies the integrity of an index block (version 2) in the image stream.
+ *
+ * Checks the CRC64 of the index block without decompressing it.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @return Status code (AARUF_STATUS_OK on success, or an error code).
+ */
 int32_t verify_index_v2(aaruformatContext *ctx)
 {
     TRACE("Entering verify_index_v2(%p)", ctx);

src/index/index_v3.c

@@ -25,6 +25,14 @@
 #include "log.h"
 #include "utarray.h"
 
+/**
+ * @brief Processes an index block (version 3) from the image stream.
+ *
+ * Reads and parses an index block (version 3) from the image, returning an array of index entries.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @return Pointer to a UT_array of IndexEntry structures, or NULL on failure.
+ */
 UT_array *process_index_v3(aaruformatContext *ctx)
 {
     TRACE("Entering process_index_v3(%p)", ctx);
@@ -71,7 +79,15 @@ UT_array *process_index_v3(aaruformatContext *ctx)
     return index_entries;
 }
 
-// Add entries from a subindex to the array of index entries
+/**
+ * @brief Adds entries from a subindex block (version 3) to the main index entries array.
+ *
+ * Recursively reads subindex blocks and appends their entries to the main index entries array.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @param index_entries Pointer to the UT_array of main index entries.
+ * @param subindex_entry Pointer to the subindex entry to process.
+ */
 void add_subindex_entries(aaruformatContext *ctx, UT_array *index_entries, IndexEntry *subindex_entry)
 {
     TRACE("Entering add_subindex_entries(%p, %p, %p)", ctx, index_entries, subindex_entry);
@@ -112,6 +128,14 @@ void add_subindex_entries(aaruformatContext *ctx, UT_array *index_entries, Index
     TRACE("Exiting add_subindex_entries() after adding %d entries", subindex_header.entries);
 }
 
+/**
+ * @brief Verifies the integrity of an index block (version 3) in the image stream.
+ *
+ * Checks the CRC64 of the index block and all subindexes without decompressing them.
+ *
+ * @param ctx Pointer to the aaruformat context.
+ * @return Status code (AARUF_STATUS_OK on success, or an error code).
+ */
 int32_t verify_index_v3(aaruformatContext *ctx)
 {
     TRACE("Entering verify_index_v3(%p)", ctx);

src/lru.c

@@ -12,6 +12,15 @@
 // by Jehiah Czebotar 2011 - jehiah@gmail.com
 // this code is in the public domain http://unlicense.org/
 
+/**
+ * @brief Finds a value in the cache by string key and updates its LRU position.
+ *
+ * Searches for a cache entry by key. If found, moves it to the front (most recently used).
+ *
+ * @param cache Pointer to the cache header.
+ * @param key String key to search for.
+ * @return Pointer to the value if found, or NULL if not found.
+ */
 void *find_in_cache(struct CacheHeader *cache, char *key)
 {
     struct CacheEntry *entry;
@@ -26,6 +35,15 @@ void *find_in_cache(struct CacheHeader *cache, char *key)
     return NULL;
 }
 
+/**
+ * @brief Adds a value to the cache with a string key, pruning if necessary.
+ *
+ * Adds a new entry to the cache. If the cache exceeds its maximum size, prunes the least recently used entry.
+ *
+ * @param cache Pointer to the cache header.
+ * @param key String key to add.
+ * @param value Pointer to the value to store.
+ */
 void add_to_cache(struct CacheHeader *cache, char *key, void *value)
 {
     struct CacheEntry *entry, *tmp_entry;
@@ -57,11 +75,29 @@ FORCE_INLINE char *int64_to_string(uint64_t number)
     return charKey;
 }
 
+/**
+ * @brief Finds a value in the cache by uint64_t key, using string conversion.
+ *
+ * Converts the uint64_t key to a string and searches for the entry in the cache.
+ *
+ * @param cache Pointer to the cache header.
+ * @param key 64-bit integer key to search for.
+ * @return Pointer to the value if found, or NULL if not found.
+ */
 void *find_in_cache_uint64(struct CacheHeader *cache, uint64_t key)
 {
     return find_in_cache(cache, int64_to_string(key));
 }
 
+/**
+ * @brief Adds a value to the cache with a uint64_t key, using string conversion.
+ *
+ * Converts the uint64_t key to a string and adds the entry to the cache.
+ *
+ * @param cache Pointer to the cache header.
+ * @param key 64-bit integer key to add.
+ * @param value Pointer to the value to store.
+ */
 void add_to_cache_uint64(struct CacheHeader *cache, uint64_t key, void *value)
 {
     return add_to_cache(cache, int64_to_string(key), value);

src/open.c

@@ -28,6 +28,14 @@
 #include "log.h"
 #include "utarray.h"
 
+/**
+ * @brief Opens an existing AaruFormat image file.
+ *
+ * Opens the specified image file and returns a pointer to the initialized aaruformat context.
+ *
+ * @param filepath Path to the image file to open.
+ * @return Pointer to the opened aaruformat context, or NULL on failure.
+ */
 void *aaruf_open(const char *filepath)
 {
     aaruformatContext *ctx           = NULL;

src/options.c

@@ -27,6 +27,14 @@
 
 #include "log.h"
 
+/**
+ * @brief Parses the options string for AaruFormat image creation/opening.
+ *
+ * Parses the options string and returns a struct with the parsed options for image creation or opening.
+ *
+ * @param options String with options to parse (may be NULL).
+ * @return Parsed options as an aaru_options struct.
+ */
 aaru_options parse_options(const char *options)
 {
     TRACE("Entering parse_options(%s)", options);

src/read.c

@@ -24,6 +24,17 @@
 #include "internal.h"
 #include "log.h"
 
+/**
+ * @brief Reads a media tag from the AaruFormat image.
+ *
+ * Reads the specified media tag from the image and stores it in the provided buffer.
+ *
+ * @param context Pointer to the aaruformat context.
+ * @param data Pointer to the buffer to store the tag data.
+ * @param tag Tag identifier to read.
+ * @param length Pointer to the length of the buffer; updated with the actual length read.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t aaruf_read_media_tag(void *context, uint8_t *data, int32_t tag, uint32_t *length)
 {
     TRACE("Entering aaruf_read_media_tag(%p, %p, %d, %u)", context, data, tag, *length);

src/time.c

@@ -34,6 +34,13 @@ uint64_t get_filetime_uint64()
 #else
 #include <sys/time.h>
 
+/**
+ * @brief Gets the current time as a 64-bit FILETIME value.
+ *
+ * Returns the current system time as a 64-bit value compatible with Windows FILETIME (number of 100-nanosecond intervals since January 1, 1601 UTC).
+ *
+ * @return The current time as a 64-bit FILETIME value.
+ */
 uint64_t get_filetime_uint64()
 {
     struct timeval tv;
@@ -44,3 +51,4 @@ uint64_t get_filetime_uint64()
     return ft;
 }
 #endif
+

src/verify.c

@@ -25,6 +25,14 @@
 
 #define VERIFY_SIZE 1048576
 
+/**
+ * @brief Verifies the integrity of an AaruFormat image file.
+ *
+ * Checks the integrity of all blocks and deduplication tables in the image.
+ *
+ * @param context Pointer to the aaruformat context.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t aaruf_verify_image(void *context)
 {
     TRACE("Entering aaruf_verify_image(%p)", context);

src/write.c

@@ -26,6 +26,18 @@
 #include "internal.h"
 #include "log.h"
 
+/**
+ * @brief Writes a sector to the AaruFormat image.
+ *
+ * Writes the given data to the specified sector address in the image, with the given status and length.
+ *
+ * @param context Pointer to the aaruformat context.
+ * @param sectorAddress Logical sector address to write.
+ * @param data Pointer to the data buffer to write.
+ * @param sectorStatus Status of the sector to write.
+ * @param length Length of the data buffer.
+ * @return AARUF_STATUS_OK on success, or an error code on failure.
+ */
 int32_t aaruf_write_sector(void *context, uint64_t sectorAddress, uint8_t *data, uint8_t sectorStatus, uint32_t length)
 {
     TRACE("Entering aaruf_write_sector(%p, %" PRIu64 ", %p, %u, %u)", context, sectorAddress, data, sectorStatus,