From af503f210a600954dca29b622cef9cc84290c34a Mon Sep 17 00:00:00 2001
From: William Pitcock <nenolod@dereferenced.org>
Date: Sat, 10 Dec 2016 19:57:26 -0600
Subject: [PATCH] libpkgconf: document dependency module

---
 doc/libpkgconf-dependency.rst | 54 +++++++++++++++++++++++++
 doc/libpkgconf.rst            |  1 +
 libpkgconf/dependency.c       | 76 ++++++++++++++++++++++++++++++++---
 3 files changed, 125 insertions(+), 6 deletions(-)
 create mode 100644 doc/libpkgconf-dependency.rst

diff --git a/doc/libpkgconf-dependency.rst b/doc/libpkgconf-dependency.rst
new file mode 100644
index 0000000..55bfbd3
--- /dev/null
+++ b/doc/libpkgconf-dependency.rst
@@ -0,0 +1,54 @@
+
+libpkgconf `dependency` module
+==============================
+
+The `dependency` module provides support for building `dependency lists` (the basic component of the overall `dependency graph`) and
+`dependency nodes` which store dependency information.
+
+.. c:function:: pkgconf_dependency_t *pkgconf_dependency_add(pkgconf_list_t *list, const char *package, const char *version, pkgconf_pkg_comparator_t compare)
+
+   Adds a parsed dependency to a dependency list as a dependency node.
+
+   :param pkgconf_list_t* list: The dependency list to add a dependency node to.
+   :param char* package: The package `atom` to set on the dependency node.
+   :param char* version: The package `version` to set on the dependency node.
+   :param pkgconf_pkg_comparator_t compare: The comparison operator to set on the dependency node.
+   :return: A dependency node.
+   :rtype: pkgconf_dependency_t *
+
+.. c:function:: void pkgconf_dependency_append(pkgconf_list_t *list, pkgconf_dependency_t *tail)
+
+   Adds a dependency node to a pre-existing dependency list.
+
+   :param pkgconf_list_t* list: The dependency list to add a dependency node to.
+   :param pkgconf_dependency_t* tail: The dependency node to add to the tail of the dependency list.
+   :return: nothing
+
+.. c:function:: void pkgconf_dependency_free(pkgconf_list_t *list)
+
+   Release a dependency list and it's child dependency nodes.
+
+   :param pkgconf_list_t* list: The dependency list to release.
+   :return: nothing
+
+.. c:function:: void pkgconf_dependency_parse_str(pkgconf_list_t *deplist_head, const char *depends)
+
+   Parse a dependency declaration into a dependency list.
+   Commas are counted as whitespace to allow for constructs such as ``@SUBSTVAR@, zlib`` being processed
+   into ``, zlib``.
+
+   :param pkgconf_list_t* deplist_head: The dependency list to populate with dependency nodes.
+   :param char* depends: The dependency data to parse.
+   :return: nothing
+
+.. c:function:: void pkgconf_dependency_parse(const pkgconf_client_t *client, pkgconf_pkg_t *pkg, pkgconf_list_t *deplist, const char *depends)
+
+   Preprocess dependency data and then process that dependency declaration into a dependency list.
+   Commas are counted as whitespace to allow for constructs such as ``@SUBSTVAR@, zlib`` being processed
+   into ``, zlib``.
+
+   :param pkgconf_client_t* client: The client object that owns the package this dependency list belongs to.
+   :param pkgconf_pkg_t* pkg: The package object that owns this dependency list.
+   :param pkgconf_list_t* deplist: The dependency list to populate with dependency nodes.
+   :param char* depends: The dependency data to parse.
+   :return: nothing
diff --git a/doc/libpkgconf.rst b/doc/libpkgconf.rst
index 29b14de..ea54dcd 100644
--- a/doc/libpkgconf.rst
+++ b/doc/libpkgconf.rst
@@ -8,3 +8,4 @@ libpkgconf - an API for managing `pkg-config` modules
    libpkgconf-audit
    libpkgconf-cache
    libpkgconf-client
+   libpkgconf-dependency
diff --git a/libpkgconf/dependency.c b/libpkgconf/dependency.c
index b8a80b2..ca84f5f 100644
--- a/libpkgconf/dependency.c
+++ b/libpkgconf/dependency.c
@@ -16,14 +16,15 @@
 #include <libpkgconf/libpkgconf.h>
 
 /*
- * pkgconf_dependency_parse(pkg, depends)
+ * !doc
  *
- * Add requirements to a .pc file.
- * Commas are counted as whitespace, as to allow:
- *    @SUBSTVAR@, zlib
- * getting substituted to:
- *    , zlib.
+ * libpkgconf `dependency` module
+ * ==============================
+ *
+ * The `dependency` module provides support for building `dependency lists` (the basic component of the overall `dependency graph`) and
+ * `dependency nodes` which store dependency information.
  */
+
 typedef enum {
 	OUTSIDE_MODULE = 0,
 	INSIDE_MODULE_NAME = 1,
@@ -53,6 +54,20 @@ pkgconf_dependency_addraw(pkgconf_list_t *list, const char *package, size_t pack
 	return dep;
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: pkgconf_dependency_t *pkgconf_dependency_add(pkgconf_list_t *list, const char *package, const char *version, pkgconf_pkg_comparator_t compare)
+ *
+ *    Adds a parsed dependency to a dependency list as a dependency node.
+ *
+ *    :param pkgconf_list_t* list: The dependency list to add a dependency node to.
+ *    :param char* package: The package `atom` to set on the dependency node.
+ *    :param char* version: The package `version` to set on the dependency node.
+ *    :param pkgconf_pkg_comparator_t compare: The comparison operator to set on the dependency node.
+ *    :return: A dependency node.
+ *    :rtype: pkgconf_dependency_t *
+ */
 pkgconf_dependency_t *
 pkgconf_dependency_add(pkgconf_list_t *list, const char *package, const char *version, pkgconf_pkg_comparator_t compare)
 {
@@ -62,12 +77,33 @@ pkgconf_dependency_add(pkgconf_list_t *list, const char *package, const char *ve
 	return pkgconf_dependency_addraw(list, package, strlen(package), NULL, 0, compare);
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: void pkgconf_dependency_append(pkgconf_list_t *list, pkgconf_dependency_t *tail)
+ *
+ *    Adds a dependency node to a pre-existing dependency list.
+ *
+ *    :param pkgconf_list_t* list: The dependency list to add a dependency node to.
+ *    :param pkgconf_dependency_t* tail: The dependency node to add to the tail of the dependency list.
+ *    :return: nothing
+ */
 void
 pkgconf_dependency_append(pkgconf_list_t *list, pkgconf_dependency_t *tail)
 {
 	pkgconf_node_insert_tail(&tail->iter, tail, list);
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: void pkgconf_dependency_free(pkgconf_list_t *list)
+ *
+ *    Release a dependency list and it's child dependency nodes.
+ *
+ *    :param pkgconf_list_t* list: The dependency list to release.
+ *    :return: nothing
+ */
 void
 pkgconf_dependency_free(pkgconf_list_t *list)
 {
@@ -87,6 +123,19 @@ pkgconf_dependency_free(pkgconf_list_t *list)
 	}
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: void pkgconf_dependency_parse_str(pkgconf_list_t *deplist_head, const char *depends)
+ *
+ *    Parse a dependency declaration into a dependency list.
+ *    Commas are counted as whitespace to allow for constructs such as ``@SUBSTVAR@, zlib`` being processed
+ *    into ``, zlib``.
+ *
+ *    :param pkgconf_list_t* deplist_head: The dependency list to populate with dependency nodes.
+ *    :param char* depends: The dependency data to parse.
+ *    :return: nothing
+ */
 void
 pkgconf_dependency_parse_str(pkgconf_list_t *deplist_head, const char *depends)
 {
@@ -217,6 +266,21 @@ pkgconf_dependency_parse_str(pkgconf_list_t *deplist_head, const char *depends)
 	}
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: void pkgconf_dependency_parse(const pkgconf_client_t *client, pkgconf_pkg_t *pkg, pkgconf_list_t *deplist, const char *depends)
+ *
+ *    Preprocess dependency data and then process that dependency declaration into a dependency list.
+ *    Commas are counted as whitespace to allow for constructs such as ``@SUBSTVAR@, zlib`` being processed
+ *    into ``, zlib``.
+ *
+ *    :param pkgconf_client_t* client: The client object that owns the package this dependency list belongs to.
+ *    :param pkgconf_pkg_t* pkg: The package object that owns this dependency list.
+ *    :param pkgconf_list_t* deplist: The dependency list to populate with dependency nodes.
+ *    :param char* depends: The dependency data to parse.
+ *    :return: nothing
+ */
 void
 pkgconf_dependency_parse(const pkgconf_client_t *client, pkgconf_pkg_t *pkg, pkgconf_list_t *deplist, const char *depends)
 {