docs(internal): correct Doxygen markup in header files

docs/EXAMPLES.md

@@ -673,7 +673,7 @@ dictionary format and §3.1 for the header fields.
 
 Consuming zxc as a Meson subproject or through WrapDB — the `.wrap` file, the
 `meson.build` dependency and the build commands — is documented in
-[INSTALL.md](INSTALL.md#meson-subproject-or-wrapdb).
+[INSTALL.md](https://github.com/hellobertrand/zxc/blob/main/docs/INSTALL.md#meson-subproject-or-wrapdb).
 
 ---
 

include/zxc_stream.h

@@ -134,8 +134,8 @@ ZXC_EXPORT int zxc_stream_get_frame_info(FILE* f_in, zxc_frame_info_t* info, siz
  * @param[in]  end        Offset just past the frame; at most the file size.
  * @param[out] info       Filled on success, untouched otherwise.
  * @param[in]  info_size  `sizeof(*info)` as the caller compiled it.
- * @return @ref ZXC_OK, or a negative @ref zxc_error_t: @ref ZXC_ERROR_SRC_TOO_SMALL
- *         past the end of the file, @ref ZXC_ERROR_IO included.
+ * @return @ref ZXC_OK, or a negative @ref zxc_error_t (@ref ZXC_ERROR_SRC_TOO_SMALL
+ *         past the end of the file, @ref ZXC_ERROR_IO included).
  */
 ZXC_EXPORT int zxc_stream_get_last_frame_info(FILE* f_in, uint64_t end, zxc_frame_info_t* info,
                                               size_t info_size);

src/lib/zxc_compress.c

@@ -242,9 +242,15 @@ static ZXC_ALWAYS_INLINE int zxc_emit_extra(uint8_t* RESTRICT extras, size_t* RE
  * @brief Emits one GLO sequence (token, offset, LL/ML escapes) and updates
  *        @p max_offset, the block's widest biased offset.
  *
- * @param[in] ll         Literal length (raw).
- * @param[in] ml         Match length minus ZXC_LZ_MIN_MATCH_LEN.
- * @param[in] off_biased Offset minus ZXC_LZ_OFFSET_BIAS.
+ * @param[out]    buf_tokens  Token stream; the token goes at index @p *seq_c.
+ * @param[out]    buf_offsets Offset stream, same index.
+ * @param[out]    buf_extras  Extras stream, for the LL/ML excess varints.
+ * @param[in,out] seq_c       Sequence count, advanced on success.
+ * @param[in,out] extras_sz   Bytes used in @p buf_extras.
+ * @param[in,out] max_offset  Widest biased offset so far.
+ * @param[in]     ll          Literal length (raw).
+ * @param[in]     ml          Match length minus ZXC_LZ_MIN_MATCH_LEN.
+ * @param[in]     off_biased  Offset minus ZXC_LZ_OFFSET_BIAS.
  * @return 1, or 0 when a length exceeds ZXC_MAX_VARINT_VALUE. The extras buffer
  *         is sized by the layout, not checked here.
  */
@@ -355,9 +361,14 @@ static int zxc_glo_split_analyze(const uint8_t* RESTRICT tokens, const uint32_t
  * consumes at least ZXC_LZ_MIN_MATCH_LEN input bytes, so the count fits the
  * block's sequence buffers.
  *
- * @param[out] side     Scratch, one byte per sequence (zxc_cctx_t::buf_split).
- * @param[out] hist_buf Scratch (zxc_cctx_t::buf_split_hist).
- * @param[in]  cap      zxc_lz77_params_t::split_max.
+ * @param[in,out] tokens    The block's tokens, rewritten in place.
+ * @param[in,out] offsets   Its offsets, rewritten in place.
+ * @param[in,out] extras    Its extras, compacted in place.
+ * @param[in,out] extras_sz Bytes used in @p extras.
+ * @param[out]    side      Scratch, one byte per sequence (zxc_cctx_t::buf_split).
+ * @param[out]    hist_buf  Scratch (zxc_cctx_t::buf_split_hist).
+ * @param[in]     n_seq     Sequence count of the block.
+ * @param[in]     cap       zxc_lz77_params_t::split_max.
  * @return The new sequence count (unchanged when the block is not split).
  */
 static uint32_t zxc_glo_split_block(uint8_t* RESTRICT tokens, uint16_t* RESTRICT offsets,

src/lib/zxc_dispatch.c

@@ -798,6 +798,9 @@ static int64_t zxc_dctx_decode_container(zxc_dctx* dctx, const uint8_t* src, siz
  * The footer's compressed size must be the whole input: one frame, starting at
  * offset 0. Each caller adds its own policy on the result.
  *
+ * @param[in]  src        The frame.
+ * @param[in]  src_size   Its size.
+ * @param[out] info       Filled on success.
  * @param[out] footer_len Footer bytes, digest included; may be NULL.
  */
 static int zxc_buffer_frame_info(const uint8_t* src, const size_t src_size, zxc_frame_info_t* info,

src/lib/zxc_driver.c

@@ -405,7 +405,10 @@ static int64_t zxc_stream_read_at(const zxc_stream_ctx_t* ctx, void* dst, const
  * @brief Reads up to @p len input bytes on the reader thread: by position while
  *        the engine reads positioned, through stdio otherwise.
  *
- * @param[in] ctx Started engine, or NULL to read through stdio.
+ * @param[in]  ctx Started engine, or NULL to read through stdio.
+ * @param[in]  f   The input stream.
+ * @param[out] dst Destination.
+ * @param[in]  len Bytes wanted.
  * @return Bytes read, short only at the end of the input, or @ref ZXC_ERROR_IO.
  */
 static int64_t zxc_stream_in_read(zxc_stream_ctx_t* ctx, FILE* f, void* dst, const size_t len) {
@@ -753,7 +756,9 @@ static void zxc_stream_engine_stop(zxc_stream_engine_t* e, const int writer_star
  * The caller fills the run's fields of @c e->ctx (mode, level, block size,
  * checksums, dictionary, progress) and of @c e->w (output, seek table, counters).
  *
- * @param[in] n_threads Thread count; 0 or less auto-detects the online processors.
+ * @param[in,out] e         The engine, its run fields filled.
+ * @param[in]     f_in      The input stream.
+ * @param[in]     n_threads Thread count; 0 or less auto-detects the online processors.
  * @return @ref ZXC_OK, or @ref ZXC_ERROR_MEMORY with nothing left to free.
  */
 static int zxc_stream_engine_start(zxc_stream_engine_t* e, FILE* f_in, const int n_threads) {
@@ -1118,7 +1123,11 @@ static void zxc_stream_finish_decompress(zxc_stream_ctx_t* ctx, const uint64_t f
 /**
  * @brief Reads exactly @p len bytes, telling a clean end from a short read.
  *
- * @param[in] ctx Started engine, or NULL before the first frame.
+ * @param[in]  ctx        Started engine, or NULL before the first frame.
+ * @param[in]  f          The input stream.
+ * @param[out] dst        Destination.
+ * @param[in]  len        Bytes to read.
+ * @param[in]  short_code Returned when the input ends inside the range.
  * @return @ref ZXC_OK; 1 when the input ended before the first byte;
  *         @p short_code when it ended inside the range; @ref ZXC_ERROR_IO on
  *         a read error.
@@ -1134,7 +1143,14 @@ static int zxc_stream_read_exact(zxc_stream_ctx_t* ctx, FILE* f, void* dst, cons
 /**
  * @brief Reads and checks a frame header whose magic word is already read.
  *
- * @param[in] dict_id Id of the caller's dictionary, 0 without one.
+ * @param[in]  ctx          Started engine, or NULL before the first frame.
+ * @param[in]  f_in         The input stream, just past the magic word.
+ * @param[in]  magic        The magic word's 4 bytes.
+ * @param[in]  dict_id      Id of the caller's dictionary, 0 without one.
+ * @param[out] chunk        The frame's block size.
+ * @param[out] has_checksum Whether the frame carries checksums.
+ * @param[out] has_seek     Whether it ends with a seek table.
+ * @return @ref ZXC_OK, or a negative @ref zxc_error_t.
  */
 static int zxc_stream_read_frame_header(zxc_stream_ctx_t* ctx, FILE* f_in, const uint8_t* magic,
                                         const uint32_t dict_id, size_t* chunk, int* has_checksum,

src/lib/zxc_huffman.c

@@ -661,6 +661,7 @@ static uint64_t zxc_huf_nudge_dp_run_j(const int lu, const int lc, const int g_l
  * Iteration order and strict-improvement relaxation are fixed, so the result
  * is deterministic.
  *
+ * @param[in]  ws       Workspace for the DP planes.
  * @param[in]  pfg      Group-mass prefix sums in frequency-rank order.
  * @param[in]  m        Number of coarse symbols (groups), >= 2.
  * @param[in]  cap_c    Coarse code-length cap (`real cap - g_log2`).

src/lib/zxc_internal.h

@@ -2324,7 +2324,11 @@ int zxc_write_file_footer(uint8_t* RESTRICT dst, const size_t dst_capacity, cons
  * Compares only the bytes present: a mismatch is corruption, a matching but
  * short prefix a truncation.
  *
- * @param[out] digest  The stored digest, 0 without checksums; may be NULL.
+ * @param[in]  footer   The footer bytes read so far.
+ * @param[in]  avail    How many there are.
+ * @param[in]  l        The layout the frame implies.
+ * @param[in]  src_size The decompressed size the footer must store.
+ * @param[out] digest   The stored digest, 0 without checksums; may be NULL.
  * @return @ref ZXC_OK, @ref ZXC_ERROR_CORRUPT_DATA or @ref ZXC_ERROR_SRC_TOO_SMALL.
  */
 int zxc_check_file_footer(const uint8_t* footer, size_t avail, const zxc_footer_layout_t* l,
@@ -2352,8 +2356,8 @@ int zxc_parse_file_footer(const uint8_t* end, size_t avail, uint64_t* src_size,
 /** @brief Smallest frame: header, the EOF block and the shortest footer. */
 #define ZXC_FRAME_MIN_SIZE (ZXC_FILE_HEADER_SIZE + ZXC_BLOCK_HEADER_SIZE + ZXC_FILE_FOOTER_MIN_SIZE)
 
-/** @brief Bytes zxc_read_frame_info() takes from the end of @p total bytes, at
- *  least @ref ZXC_FRAME_MIN_SIZE: all of them past the header and EOF block, up
+/** @brief Bytes zxc_read_frame_info() takes from the end of @p total bytes (at
+ *  least @ref ZXC_FRAME_MIN_SIZE): all of them past the header and EOF block, up
  *  to @ref ZXC_FOOTER_MAX_SIZE_WITH_DIGEST. */
 static inline size_t zxc_frame_tail_len(const uint64_t total) {
     const uint64_t body = total - (ZXC_FILE_HEADER_SIZE + ZXC_BLOCK_HEADER_SIZE);
@@ -2365,8 +2369,8 @@ static inline size_t zxc_frame_tail_len(const uint64_t total) {
  *        check behind zxc_get_frame_info(), its FILE* twin and the size queries.
  *
  * @param[in]  header     The first @ref ZXC_FILE_HEADER_SIZE bytes.
- * @param[in]  tail       The last @p tail_len bytes, @p tail_len being
- *                        @ref zxc_frame_tail_len of @p total.
+ * @param[in]  tail       The last @p tail_len bytes of the input.
+ * @param[in]  tail_len   @ref zxc_frame_tail_len of @p total.
  * @param[in]  total      Bytes of the whole input.
  * @param[out] info       Filled on success.
  * @param[out] footer_len Footer bytes, digest included; may be NULL.

src/lib/zxc_seekable.c

@@ -159,7 +159,7 @@ static zxc_seek_source_t zxc_seek_source_of(const zxc_seekable* s) {
     return src;
 }
 
-/** @brief @ref zxc_scan_src_t over a @ref zxc_seek_source_t. */
+/** @brief @ref zxc_scan_src_t over a @c zxc_seek_source_t. */
 static int zxc_seek_scan_read(const zxc_scan_src_t* scan, const uint64_t off, void* dst,
                               const size_t len) {
     return zxc_seek_source_read((const zxc_seek_source_t*)scan->ctx, dst, len, off);
@@ -170,7 +170,9 @@ static int zxc_seek_scan_read(const zxc_scan_src_t* scan, const uint64_t off, vo
  *        footer as zxc_get_last_frame_info() does. Its EOF and SEK headers are
  *        checked with its table, on access (@ref zxc_seek_load_spans).
  *
- * @param[out] f  The frame; its decompressed and block bases are left to the caller.
+ * @param[in]  src The archive.
+ * @param[in]  end Offset just past the frame.
+ * @param[out] f   The frame; its decompressed and block bases are left to the caller.
  * @return 1 for a seekable frame, 0 otherwise.
  */
 static int zxc_seek_parse_frame(zxc_seek_source_t* src, const uint64_t end, zxc_seek_frame_t* f) {
@@ -681,23 +683,15 @@ typedef struct {
  * Lives on the caller's stack: the caller's output pointer therefore never
  * reaches heap memory (jobs carry offsets into it), and there is no per-thread
  * array to size for @c ZXC_MAX_THREADS.
- *
- * @var zxc_seek_mt_shared_t::s          Handle being read (read-only).
- * @var zxc_seek_mt_shared_t::jobs       Job array; each worker touches only its stripe.
- * @var zxc_seek_mt_shared_t::dst_base   Start of the caller's output buffer.
- * @var zxc_seek_mt_shared_t::num_jobs   Job count (stripe iteration bound).
- * @var zxc_seek_mt_shared_t::stride     Worker count attempted; stripes partition by it.
- * @var zxc_seek_mt_shared_t::next       Next stripe index to hand out, under @c lock.
- * @var zxc_seek_mt_shared_t::lock       Guards @c next.
  */
 typedef struct {
-    const zxc_seekable* s;
-    zxc_seek_mt_job_t* jobs;
-    uint8_t* dst_base;
-    uint32_t num_jobs;
-    uint32_t stride;
-    uint32_t next;
-    pthread_mutex_t lock;
+    const zxc_seekable* s;   /* handle being read (read-only) */
+    zxc_seek_mt_job_t* jobs; /* job array; each worker touches only its stripe */
+    uint8_t* dst_base;       /* start of the caller's output buffer */
+    uint32_t num_jobs;       /* job count (stripe iteration bound) */
+    uint32_t stride;         /* worker count attempted; stripes partition by it */
+    uint32_t next;           /* next stripe index to hand out, under lock */
+    pthread_mutex_t lock;    /* guards next */
 } zxc_seek_mt_shared_t;
 
 /**