libpkgconf: document path module

doc/libpkgconf-path.rst

@@ -0,0 +1,51 @@
+
+libpkgconf `path` module
+========================
+
+The `path` module provides functions for manipulating lists of paths in a cross-platform manner.  Notably,
+it is used by the `pkgconf client` to parse the ``PKG_CONFIG_PATH``, ``PKG_CONFIG_LIBDIR`` and related environment
+variables.
+
+.. c:function:: void pkgconf_path_add(const char *text, pkgconf_list_t *dirlist)
+
+   Adds a path node to a path list.
+
+   :param char* text: The path text to add as a path node.
+   :param pkgconf_list_t* dirlist: The path list to add the path node to.
+   :return: nothing
+
+.. c:function:: size_t pkgconf_path_split(const char *text, pkgconf_list_t *dirlist)
+
+   Splits a given text input and inserts paths into a path list.
+
+   :param char* text: The path text to split and add as path nodes.
+   :param pkgconf_list_t* dirlist: The path list to have the path nodes added to.
+   :return: number of path nodes added to the path list
+   :rtype: size_t
+
+.. c:function:: size_t pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgconf_list_t *dirlist)
+
+   Adds the paths specified in an environment variable to a path list.  If the environment variable is not set,
+   an optional default set of paths is added.
+
+   :param char* environ: The environment variable to look up.
+   :param char* fallback: The fallback paths to use if the environment variable is not set.
+   :param pkgconf_list_t* dirlist: The path list to add the path nodes to.
+   :return: number of path nodes added to the path list
+   :rtype: size_t
+
+.. c:function:: bool pkgconf_path_match_list(const char *path, pkgconf_list_t *dirlist)
+
+   Checks whether a path has a matching prefix in a path list.
+
+   :param char* path: The path to check against a path list.
+   :param pkgconf_list_t* dirlist: The path list to check the path against.
+   :return: true if the path list has a matching prefix, otherwise false
+   :rtype: bool
+
+.. c:function:: void pkgconf_path_free(pkgconf_list_t *dirlist)
+
+   Releases any path nodes attached to the given path list.
+
+   :param pkgconf_list_t* dirlist: The path list to clean up.
+   :return: nothing

doc/libpkgconf.rst

@@ -9,3 +9,4 @@ libpkgconf - an API for managing `pkg-config` modules
    libpkgconf-cache
    libpkgconf-client
    libpkgconf-dependency
+   libpkgconf-path

libpkgconf/path.c

@@ -15,6 +15,28 @@
 
 #include <libpkgconf/libpkgconf.h>
 
+/*
+ * !doc
+ *
+ * libpkgconf `path` module
+ * ========================
+ *
+ * The `path` module provides functions for manipulating lists of paths in a cross-platform manner.  Notably,
+ * it is used by the `pkgconf client` to parse the ``PKG_CONFIG_PATH``, ``PKG_CONFIG_LIBDIR`` and related environment
+ * variables.
+ */
+
+/*
+ * !doc
+ *
+ * .. c:function:: void pkgconf_path_add(const char *text, pkgconf_list_t *dirlist)
+ *
+ *    Adds a path node to a path list.
+ *
+ *    :param char* text: The path text to add as a path node.
+ *    :param pkgconf_list_t* dirlist: The path list to add the path node to.
+ *    :return: nothing
+ */
 void
 pkgconf_path_add(const char *text, pkgconf_list_t *dirlist)
 {
@@ -26,6 +48,18 @@ pkgconf_path_add(const char *text, pkgconf_list_t *dirlist)
 	pkgconf_node_insert_tail(&node->lnode, node, dirlist);
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: size_t pkgconf_path_split(const char *text, pkgconf_list_t *dirlist)
+ *
+ *    Splits a given text input and inserts paths into a path list.
+ *
+ *    :param char* text: The path text to split and add as path nodes.
+ *    :param pkgconf_list_t* dirlist: The path list to have the path nodes added to.
+ *    :return: number of path nodes added to the path list
+ *    :rtype: size_t
+ */
 size_t
 pkgconf_path_split(const char *text, pkgconf_list_t *dirlist)
 {
@@ -47,6 +81,20 @@ pkgconf_path_split(const char *text, pkgconf_list_t *dirlist)
 	return count;
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: size_t pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgconf_list_t *dirlist)
+ *
+ *    Adds the paths specified in an environment variable to a path list.  If the environment variable is not set,
+ *    an optional default set of paths is added.
+ *
+ *    :param char* environ: The environment variable to look up.
+ *    :param char* fallback: The fallback paths to use if the environment variable is not set.
+ *    :param pkgconf_list_t* dirlist: The path list to add the path nodes to.
+ *    :return: number of path nodes added to the path list
+ *    :rtype: size_t
+ */
 size_t
 pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgconf_list_t *dirlist)
 {
@@ -63,6 +111,18 @@ pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgco
 	return 0;
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: bool pkgconf_path_match_list(const char *path, pkgconf_list_t *dirlist)
+ *
+ *    Checks whether a path has a matching prefix in a path list.
+ *
+ *    :param char* path: The path to check against a path list.
+ *    :param pkgconf_list_t* dirlist: The path list to check the path against.
+ *    :return: true if the path list has a matching prefix, otherwise false
+ *    :rtype: bool
+ */
 bool
 pkgconf_path_match_list(const char *path, pkgconf_list_t *dirlist)
 {
@@ -79,6 +139,16 @@ pkgconf_path_match_list(const char *path, pkgconf_list_t *dirlist)
 	return false;
 }
 
+/*
+ * !doc
+ *
+ * .. c:function:: void pkgconf_path_free(pkgconf_list_t *dirlist)
+ *
+ *    Releases any path nodes attached to the given path list.
+ *
+ *    :param pkgconf_list_t* dirlist: The path list to clean up.
+ *    :return: nothing
+ */
 void
 pkgconf_path_free(pkgconf_list_t *dirlist)
 {