From 9efa991d98cf8fae0d9876e2c21ac43ef16eb078 Mon Sep 17 00:00:00 2001
From: William Pitcock <nenolod@dereferenced.org>
Date: Sat, 10 Dec 2016 19:40:51 -0600
Subject: [PATCH] libpkgconf: update cache docs to new format

---
 doc/libpkgconf-cache.rst | 45 +++++++++++++++++++++++++++++
 doc/libpkgconf.rst       |  1 +
 libpkgconf/cache.c       | 61 ++++++++++++++++++++++++++++++++++------
 3 files changed, 98 insertions(+), 9 deletions(-)
 create mode 100644 doc/libpkgconf-cache.rst

diff --git a/doc/libpkgconf-cache.rst b/doc/libpkgconf-cache.rst
new file mode 100644
index 0000000..adfa79d
--- /dev/null
+++ b/doc/libpkgconf-cache.rst
@@ -0,0 +1,45 @@
+
+libpkgconf `cache` module
+=========================
+
+The libpkgconf `cache` module manages a package/module object cache, allowing it to
+avoid loading duplicate copies of a package/module.
+
+A cache is tied to a specific pkgconf client object, so package objects should not
+be shared across threads.
+
+.. c:function:: pkgconf_pkg_t *pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id)
+
+   Looks up a package in the cache given an `id` atom,
+   such as ``gtk+-3.0`` and returns the already loaded version
+   if present.
+
+   :param pkgconf_client_t* client: The client object to access.
+   :param char* id: The package atom to look up in the client object's cache.
+   :return: A package object if present, else ``NULL``.
+   :rtype: pkgconf_pkg_t *
+
+.. c:function:: void pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
+
+   Adds an entry for the package to the package cache.
+   The cache entry must be removed if the package is freed.
+
+   :param pkgconf_client_t* client: The client object to modify.
+   :param pkgconf_pkg_t* pkg: The package object to add to the client object's cache.
+   :return: nothing
+
+.. c:function:: void pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
+
+   Deletes a package from the client object's package cache.
+
+   :param pkgconf_client_t* client: The client object to modify.
+   :param pkgconf_pkg_t* pkg: The package object to remove from the client object's cache.
+   :return: nothing
+
+.. c:function:: void pkgconf_cache_free(pkgconf_client_t *client)
+
+   Releases all resources related to a client object's package cache.
+   This function should only be called to clear a client object's package cache,
+   as it may release any package in the cache.
+
+   :param pkgconf_client_t* client: The client object to modify.
diff --git a/doc/libpkgconf.rst b/doc/libpkgconf.rst
index 82ee436..29b14de 100644
--- a/doc/libpkgconf.rst
+++ b/doc/libpkgconf.rst
@@ -6,4 +6,5 @@ libpkgconf - an API for managing `pkg-config` modules
 
    libpkgconf-argvsplit
    libpkgconf-audit
+   libpkgconf-cache
    libpkgconf-client
diff --git a/libpkgconf/cache.c b/libpkgconf/cache.c
index 03a3a32..2c5c7e8 100644
--- a/libpkgconf/cache.c
+++ b/libpkgconf/cache.c
@@ -16,11 +16,31 @@
 #include <libpkgconf/libpkgconf.h>
 
 /*
- * pkgconf_cache_lookup(id)
+ * !doc
  *
- * looks up a package in the cache given an 'id' atom,
- * such as 'gtk+-3.0' and returns the already loaded version
- * if present.
+ * libpkgconf `cache` module
+ * =========================
+ *
+ * The libpkgconf `cache` module manages a package/module object cache, allowing it to
+ * avoid loading duplicate copies of a package/module.
+ *
+ * A cache is tied to a specific pkgconf client object, so package objects should not
+ * be shared across threads.
+ */
+
+/*
+ * !doc
+ *
+ * .. c:function:: pkgconf_pkg_t *pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id)
+ *
+ *    Looks up a package in the cache given an `id` atom,
+ *    such as ``gtk+-3.0`` and returns the already loaded version
+ *    if present.
+ *
+ *    :param pkgconf_client_t* client: The client object to access.
+ *    :param char* id: The package atom to look up in the client object's cache.
+ *    :return: A package object if present, else ``NULL``.
+ *    :rtype: pkgconf_pkg_t *
  */
 pkgconf_pkg_t *
 pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id)
@@ -39,10 +59,16 @@ pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id)
 }
 
 /*
- * pkgconf_cache_add(pkg)
+ * !doc
  *
- * adds an entry for the package to the package cache.
- * the cache entry must be removed if the package is freed.
+ * .. c:function:: void pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
+ *
+ *    Adds an entry for the package to the package cache.
+ *    The cache entry must be removed if the package is freed.
+ *
+ *    :param pkgconf_client_t* client: The client object to modify.
+ *    :param pkgconf_pkg_t* pkg: The package object to add to the client object's cache.
+ *    :return: nothing
  */
 void
 pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
@@ -55,9 +81,15 @@ pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
 }
 
 /*
- * pkgconf_cache_remove(pkg)
+ * !doc
  *
- * deletes a package from the cache entry.
+ * .. c:function:: void pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
+ *
+ *    Deletes a package from the client object's package cache.
+ *
+ *    :param pkgconf_client_t* client: The client object to modify.
+ *    :param pkgconf_pkg_t* pkg: The package object to remove from the client object's cache.
+ *    :return: nothing
  */
 void
 pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
@@ -68,6 +100,17 @@ pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
 	pkgconf_node_delete(&pkg->cache_iter, &client->pkg_cache);
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: void pkgconf_cache_free(pkgconf_client_t *client)
+ *
+ *    Releases all resources related to a client object's package cache.
+ *    This function should only be called to clear a client object's package cache,
+ *    as it may release any package in the cache.
+ *
+ *    :param pkgconf_client_t* client: The client object to modify.
+ */
 void
 pkgconf_cache_free(pkgconf_client_t *client)
 {