From d79a99b0910f0cea5ec4c8332fa162c46bae2492 Mon Sep 17 00:00:00 2001
From: Patrick McDermott <patrick.mcdermott@libiquity.com>
Date: Wed, 19 Apr 2023 08:38:36 -0400
Subject: opk: Document functions

---
(limited to 'src/opk.h')

diff --git a/src/opk.h b/src/opk.h
index 1b7e681..8a8cc54 100644
--- a/src/opk.h
+++ b/src/opk.h
@@ -24,22 +24,77 @@
 
 struct opkg_opk_opk;
 
+/*
+ * Allocates and initializes a package structure.
+ * Parameters:
+ * - file_name: Package's file name.
+ * Returns:
+ * - Allocated package structure on success.  Free with
+ *   opkg_opk_opk_free_outer().
+ * - NULL on memory exhaustion.
+ */
 struct opkg_opk_opk *
 opkg_opk_opk_init_outer(const char *file_name);
 
+/*
+ * Initializes an inner archive of a package.  Free with
+ * opkg_opk_opk_free_outer().  May be called again after freeing.
+ * Parameters:
+ * - opk:    Package structure.
+ * - member: Name of member file to find and prepare to read.  Should be either
+ *   "control.tar.gz" or "data.tar.gz", in that order if both are to be read.
+ * Returns:
+ * - OPKG_OPK_OK if the inner archive is found and initialized.
+ * - OPKG_OPK_ERROR if no matching member is found or on decompression error,
+ *   premature end of gzip stream, an invalid header, unsupported file type, or
+ *   memory exhaustion.
+ */
 int
 opkg_opk_opk_init_inner(struct opkg_opk_opk *opk, const char *member);
 
+/*
+ * Reads and prints all specified control files.
+ * Parameters:
+ * - opk:   Package structure.
+ * - names: List of control file names to read.
+ * Returns:
+ * - OPKG_OPK_OK if all control files are found, read, and printed.
+ * - OPKG_OPK_ERROR if any control file is not found or on decompression error,
+ *   premature end of gzip stream, an invalid header, unsupported file type, or
+ *   error writing to standard output.
+ */
 int
 opkg_opk_opk_read_control(struct opkg_opk_opk *opk,
 		struct opkg_opk_ustar_seek_name *names);
 
+/*
+ * Lists and prints all data files.
+ * Parameters:
+ * - opk: Package structure.
+ * Returns:
+ * - OPKG_OPK_OK if all data files are listed and printed.
+ * - OPKG_OPK_ERROR on decompression error, memory exhaustion, mode or mtime
+ *   integer conversion error, unsupported file type, or error writing to
+ *   standard output.
+ */
 int
 opkg_opk_opk_list_members(struct opkg_opk_opk *opk);
 
+/*
+ * Frees a package structure's inner archive.  Call before
+ * opkg_opk_opk_free_outer() if a opkg_opk_opk_init_inner() call succeeds.
+ * Parameters:
+ * - opk: Package structure.
+ */
 void
 opkg_opk_opk_free_inner(struct opkg_opk_opk *opk);
 
+/*
+ * Frees a package structure.  Call opkg_opk_opk_free_inner() first after a
+ * successful opkg_opk_opk_init_inner() call.
+ * Parameters:
+ * - opk: Package structure.
+ */
 void
 opkg_opk_opk_free_outer(struct opkg_opk_opk *opk);
 
--
cgit v0.9.1