From 62e056a12300a276ec99a99f9061bef5fa35fe9e Mon Sep 17 00:00:00 2001
From: Patrick McDermott <patrick.mcdermott@libiquity.com>
Date: Tue, 18 Apr 2023 11:47:46 -0400
Subject: gzip, ustar: Document functions

---
diff --git a/src/gzip.h b/src/gzip.h
index 7c81463..e4c3f52 100644
--- a/src/gzip.h
+++ b/src/gzip.h
@@ -24,12 +24,44 @@ struct opkg_opk_gzip;
 
 typedef int (opkg_opk_gzip_read_func)(void *, char **, size_t *);
 
+/*
+ * Allocates and initializes a decompression structure.
+ * Parameters:
+ * - read:      Function to read compressed data.  Parameter 1 is user_data,
+ *              parameter 2 is an address in which the read function should
+ *              store an address to compressed data, and parameter 3 is an
+ *              address in which the read function should store the size of read
+ *              compressed data.  Should return OPKG_OPK_OK if data is read,
+ *              OPKG_OPK_END if no more data is available (end of file or
+ *              archive), or OPKG_OPK_ERROR on error.
+ * - user_data: Passed to read function.
+ * Returns:
+ * - Allocated decompression structure on success.  Free with
+ *   opkg_opk_gzip_free().
+ * - NULL on memory exhaustion.
+ */
 struct opkg_opk_gzip *
 opkg_opk_gzip_init(opkg_opk_gzip_read_func *read, void *user_data);
 
+/*
+ * Reads and decompresses data to output the next record (512 octets).
+ * Parameters:
+ * - gzip:   Decompression structure.
+ * - record: Address in which to store decompressed record.
+ * Returns:
+ * - OPKG_OPK_OK if a record is read and decompressed.
+ * - OPKG_OPK_END if the end of the gzip stream is reached.
+ * - OPKG_OPK_ERROR if the read function returned an error, the compressed input
+ *   data or gzip stream end prematurely, or zlib returns an error.
+ */
 int
 opkg_opk_gzip_read(struct opkg_opk_gzip *gzip, void *record);
 
+/*
+ * Frees a decompression structure.
+ * Parameters:
+ * - gzip: Decompression structure.
+ */
 void
 opkg_opk_gzip_free(struct opkg_opk_gzip *gzip);
 
diff --git a/src/ustar.h b/src/ustar.h
index 388011c..eeca53a 100644
--- a/src/ustar.h
+++ b/src/ustar.h
@@ -40,19 +40,66 @@ struct opkg_opk_ustar_member {
 	struct opkg_opk_ustar_member *next;
 };
 
+/*
+ * Allocates and initializes an archive structure.
+ * Parameters:
+ * - gzip: Decompressor for archive's gzip stream.
+ * Returns:
+ * - Allocated archive structure on success.  Free with opkg_opk_ustar_free().
+ * - NULL on memory exhaustion.
+ */
 struct opkg_opk_ustar *
 opkg_opk_ustar_init(struct opkg_opk_gzip *gzip);
 
+/*
+ * Lists member files one at a time.
+ * Parameters:
+ * - ustar:  Archive structure.
+ * - member: Address in which to store address of allocated member structure.
+ *           Free with free().
+ * Returns:
+ * - OPKG_OPK_OK if a member was listed.  More members may exist.
+ * - OPKG_OPK_END if no more members exist.  Parameter "member" is unchanged.
+ * - OPKG_OPK_ERROR on decompression error, memory exhaustion, mode or mtime
+ *   integer conversion error, or unsupported file type.
+ */
 int
 opkg_opk_ustar_list(struct opkg_opk_ustar *ustar,
 		struct opkg_opk_ustar_member **member);
 
+/*
+ * Advances to a named member file.
+ * Parameters:
+ * - ustar:    Archive structure.
+ * - num_keys: Number of search keys to follow.
+ * - ...:      Search keys of type (const char *).
+ * Returns:
+ * - OPKG_OPK_OK if a member matching one of the search keys is found.
+ * - OPKG_OPK_ERROR if no matching member is found or on decompression error, an
+ *   invalid header, or unsupported file type.
+ */
 int
 opkg_opk_ustar_seek(struct opkg_opk_ustar *ustar, int num_keys, ...);
 
+/*
+ * Reads up to a record (512 octets) of member file data at a time.
+ * Parameters:
+ * - ustar:  Archive structure.
+ * - buffer: Address in which to store address of data buffer.  Do not free.
+ * - size:   Address in which to store size of read data.
+ * Returns:
+ * - OPKG_OPK_OK if data was read.
+ * - OPKG_OPK_END if no more data exists.
+ * - OPKG_OPK_ERROR on decompression error or premature end of gzip stream.
+ */
 int
 opkg_opk_ustar_read(struct opkg_opk_ustar *ustar, char **buffer, size_t *size);
 
+/*
+ * Frees an archive structure.
+ * Parameters:
+ * - ustar: Archive structure.
+ */
 void
 opkg_opk_ustar_free(struct opkg_opk_ustar *ustar);
 
--
cgit v0.9.1