doc: Regenerate the documentation for libpkgconf

Signed-off-by: Andrej Shadura <andrew.shadura@collabora.co.uk>

doc/extract.py

@@ -70,21 +70,21 @@ def extract_comments(filename):
             while True:
                 char = source_file.read(1)
                 if not char:
-                    if state is 3 or state is 4:
+                    if state == 3 or state == 4:
                         raise UnterminatedCommentError()
-                    if state is 2:
+                    if state == 2:
                         # Was in single line comment. Create comment.
                         comment = Comment(current_comment, line_counter, False)
                         comments.append(comment)
                     return comments
-                if state is 0:
+                if state == 0:
                     # Waiting for comment start character or beginning of
                     # string.
                     if char == '/':
                         state = 1
                     elif char == '"':
                         state = 5
-                elif state is 1:
+                elif state == 1:
                     # Found comment start character, classify next character and
                     # determine if single or multiline comment.
                     if char == '/':
@@ -94,7 +94,7 @@ def extract_comments(filename):
                         state = 3
                     else:
                         state = 0
-                elif state is 2:
+                elif state == 2:
                     # In single line comment, read characters until EOL.
                     if char == '\n':
                         comment = Comment(current_comment, line_counter, False)
@@ -103,14 +103,14 @@ def extract_comments(filename):
                         state = 0
                     else:
                         current_comment += char
-                elif state is 3:
+                elif state == 3:
                     # In multi-line comment, add characters until '*'
                     # encountered.
                     if char == '*':
                         state = 4
                     else:
                         current_comment += char
-                elif state is 4:
+                elif state == 4:
                     # In multi-line comment with asterisk found. Determine if
                     # comment is ending.
                     if char == '/':
@@ -125,13 +125,13 @@ def extract_comments(filename):
                         if char != '*':
                             current_comment += char
                             state = 3
-                elif state is 5:
+                elif state == 5:
                     # In string literal, expect literal end or escape char.
                     if char == '"':
                         state = 0
                     elif char == '\\':
                         state = 6
-                elif state is 6:
+                elif state == 6:
                     # In string literal, escaping current char.
                     state = 5
                 if char == '\n':

doc/libpkgconf-client.rst

@@ -9,21 +9,32 @@ in parallel.
 Client objects are not thread safe, in other words, a client object should not be shared across
 thread boundaries.
 
-.. c:function:: void pkgconf_client_init(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler)
+.. c:function:: void pkgconf_client_dir_list_build(pkgconf_client_t *client)
+
+   Bootstraps the package search paths.  If the ``PKGCONF_PKG_PKGF_ENV_ONLY`` `flag` is set on the client,
+   then only the ``PKG_CONFIG_PATH`` environment variable will be used, otherwise both the
+   ``PKG_CONFIG_PATH`` and ``PKG_CONFIG_LIBDIR`` environment variables will be used.
+
+   :param pkgconf_client_t* client: The pkgconf client object to bootstrap.
+   :return: nothing
+
+.. c:function:: void pkgconf_client_init(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data, const pkgconf_cross_personality_t *personality)
 
    Initialise a pkgconf client object.
 
    :param pkgconf_client_t* client: The client to initialise.
    :param pkgconf_error_handler_func_t error_handler: An optional error handler to use for logging errors.
    :param void* error_handler_data: user data passed to optional error handler
+   :param pkgconf_cross_personality_t* personality: the cross-compile personality to use for defaults
    :return: nothing
 
-.. c:function:: pkgconf_client_t* pkgconf_client_new(pkgconf_error_handler_func_t error_handler)
+.. c:function:: pkgconf_client_t* pkgconf_client_new(pkgconf_error_handler_func_t error_handler, void *error_handler_data, const pkgconf_cross_personality_t *personality)
 
    Allocate and initialise a pkgconf client object.
 
    :param pkgconf_error_handler_func_t error_handler: An optional error handler to use for logging errors.
    :param void* error_handler_data: user data passed to optional error handler
+   :param pkgconf_cross_personality_t* personality: cross-compile personality to use
    :return: A pkgconf client object.
    :rtype: pkgconf_client_t*
 
@@ -97,11 +108,14 @@ thread boundaries.
    :return: true if the warn handler processed the message, else false.
    :rtype: bool
 
-.. c:function:: bool pkgconf_trace(const pkgconf_client_t *client, const char *format, ...)
+.. c:function:: bool pkgconf_trace(const pkgconf_client_t *client, const char *filename, size_t len, const char *funcname, const char *format, ...)
 
    Report a message to a client-registered trace handler.
 
    :param pkgconf_client_t* client: The pkgconf client object to report the trace message to.
+   :param char* filename: The file the function is in.
+   :param size_t lineno: The line number currently being executed.
+   :param char* funcname: The function name to use.
    :param char* format: A printf-style format string to use for formatting the trace message.
    :return: true if the trace handler processed the message, else false.
    :rtype: bool

doc/libpkgconf-dependency.rst

@@ -14,6 +14,7 @@ The `dependency` module provides support for building `dependency lists` (the ba
    :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.
+   :param uint flags: Any flags to attach to the dependency node.
    :return: A dependency node.
    :rtype: pkgconf_dependency_t *
 
@@ -25,6 +26,29 @@ The `dependency` module provides support for building `dependency lists` (the ba
    :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_one(pkgconf_dependency_t *dep)
+
+   Frees a dependency node.
+
+   :param pkgconf_dependency_t* dep: The dependency node to free.
+   :return: nothing
+
+.. c:function:: pkgconf_dependency_t *pkgconf_dependency_ref(pkgconf_client_t *owner, pkgconf_dependency_t *dep)
+
+   Increases a dependency node's refcount.
+
+   :param pkgconf_client_t* owner: The client object which owns the memory of this dependency node.
+   :param pkgconf_dependency_t* dep: The dependency to increase the refcount of.
+   :return: the dependency node on success, else NULL
+
+.. c:function:: void pkgconf_dependency_unref(pkgconf_client_t *owner, pkgconf_dependency_t *dep)
+
+   Decreases a dependency node's refcount and frees it if necessary.
+
+   :param pkgconf_client_t* owner: The client object which owns the memory of this dependency node.
+   :param pkgconf_dependency_t* dep: The dependency to decrease the refcount of.
+   :return: nothing
+
 .. c:function:: void pkgconf_dependency_free(pkgconf_list_t *list)
 
    Release a dependency list and it's child dependency nodes.
@@ -41,6 +65,7 @@ The `dependency` module provides support for building `dependency lists` (the ba
    :param pkgconf_client_t* client: The client object that owns the package this dependency list belongs to.
    :param pkgconf_list_t* deplist_head: The dependency list to populate with dependency nodes.
    :param char* depends: The dependency data to parse.
+   :param uint flags: Any flags to attach to the dependency nodes.
    :return: nothing
 
 .. c:function:: void pkgconf_dependency_parse(const pkgconf_client_t *client, pkgconf_pkg_t *pkg, pkgconf_list_t *deplist, const char *depends)
@@ -53,4 +78,13 @@ The `dependency` module provides support for building `dependency lists` (the ba
    :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.
+   :param uint flags: Any flags to attach to the dependency nodes.
    :return: nothing
+
+.. c:function:: pkgconf_dependency_t *pkgconf_dependency_copy(pkgconf_client_t *client, const pkgconf_dependency_t *dep)
+
+   Copies a dependency node to a new one.
+
+   :param pkgconf_client_t* client: The client object that will own this dependency.
+   :param pkgconf_dependency_t* dep: The dependency node to copy.
+   :return: a pointer to a new dependency node, else NULL

doc/libpkgconf-fragment.rst

@@ -6,13 +6,14 @@ The `fragment` module provides low-level management and rendering of fragment li
 `fragment list` contains various `fragments` of text (such as ``-I /usr/include``) in a matter
 which is composable, mergeable and reorderable.
 
-.. c:function:: void pkgconf_fragment_add(const pkgconf_client_t *client, pkgconf_list_t *list, const char *string)
+.. c:function:: void pkgconf_fragment_add(const pkgconf_client_t *client, pkgconf_list_t *list, const char *string, unsigned int flags)
 
    Adds a `fragment` of text to a `fragment list`, possibly modifying the fragment if a sysroot is set.
 
    :param pkgconf_client_t* client: The pkgconf client being accessed.
    :param pkgconf_list_t* list: The fragment list.
    :param char* string: The string of text to add as a fragment to the fragment list.
+   :param uint flags: Parsing-related flags for the package.
    :return: nothing
 
 .. c:function:: bool pkgconf_fragment_has_system_dir(const pkgconf_client_t *client, const pkgconf_fragment_t *frag)
@@ -110,5 +111,6 @@ which is composable, mergeable and reorderable.
    :param pkgconf_client_t* client: The pkgconf client being accessed.
    :param pkgconf_list_t* list: The `fragment list` to add the fragment entries to.
    :param pkgconf_list_t* vars: A list of variables to use for variable substitution.
+   :param uint flags: Any parsing flags to be aware of.
    :param char* value: The string to parse into fragments.
    :return: true on success, false on parse error

doc/libpkgconf-path.rst

@@ -25,12 +25,12 @@ variables.
    :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)
+.. c:function:: size_t pkgconf_path_build_from_environ(const char *envvarname, 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* envvarname: 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.
    :param bool filter: Whether to perform duplicate filtering.
@@ -46,6 +46,14 @@ variables.
    :return: true if the path list has a matching prefix, otherwise false
    :rtype: bool
 
+.. c:function:: void pkgconf_path_copy_list(pkgconf_list_t *dst, const pkgconf_list_t *src)
+
+   Copies a path list to another path list.
+
+   :param pkgconf_list_t* dst: The path list to copy to.
+   :param pkgconf_list_t* src: The path list to copy from.
+   :return: nothing
+
 .. c:function:: void pkgconf_path_free(pkgconf_list_t *dirlist)
 
    Releases any path nodes attached to the given path list.

doc/libpkgconf-personality.rst

@@ -0,0 +1,27 @@
+
+libpkgconf `personality` module
+=========================
+
+.. c:function:: const pkgconf_cross_personality_t *pkgconf_cross_personality_default(void)
+
+   Returns the default cross-compile personality.
+
+   Not thread safe.
+
+   :rtype: pkgconf_cross_personality_t*
+   :return: the default cross-compile personality
+
+.. c:function:: void pkgconf_cross_personality_deinit(pkgconf_cross_personality_t *)
+
+   Decrements the count of default cross personality instances.
+
+   Not thread safe.
+
+   :rtype: void
+
+.. c:function:: pkgconf_cross_personality_t *pkgconf_cross_personality_find(const char *triplet)
+
+   Attempts to find a cross-compile personality given a triplet.
+
+   :rtype: pkgconf_cross_personality_t*
+   :return: the default cross-compile personality

doc/libpkgconf-pkg.rst

@@ -5,22 +5,14 @@ libpkgconf `pkg` module
 The `pkg` module provides dependency resolution services and the overall `.pc` file parsing
 routines.
 
-.. c:function:: void pkgconf_pkg_dir_list_build(pkgconf_client_t *client)
-
-   Bootstraps the package search paths.  If the ``PKGCONF_PKG_PKGF_ENV_ONLY`` `flag` is set on the client,
-   then only the ``PKG_CONFIG_PATH`` environment variable will be used, otherwise both the
-   ``PKG_CONFIG_PATH`` and ``PKG_CONFIG_LIBDIR`` environment variables will be used.
-
-   :param pkgconf_client_t* client: The pkgconf client object to bootstrap.
-   :return: nothing
-
-.. c:function:: pkgconf_pkg_t *pkgconf_pkg_new_from_file(const pkgconf_client_t *client, const char *filename, FILE *f)
+.. c:function:: pkgconf_pkg_t *pkgconf_pkg_new_from_file(const pkgconf_client_t *client, const char *filename, FILE *f, unsigned int flags)
 
    Parse a .pc file into a pkgconf_pkg_t object structure.
 
    :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
    :param char* filename: The filename of the package file (including full path).
    :param FILE* f: The file object to read from.
+   :param uint flags: The flags to use when parsing.
    :returns: A ``pkgconf_pkg_t`` object which contains the package data.
    :rtype: pkgconf_pkg_t *
 
@@ -126,7 +118,7 @@ routines.
    :return: On success, ``PKGCONF_PKG_ERRF_OK`` (0), else an error code.
    :rtype: unsigned int
 
-.. c:function:: unsigned int pkgconf_pkg_traverse(pkgconf_client_t *client, pkgconf_pkg_t *root, pkgconf_pkg_traverse_func_t func, void *data, int maxdepth)
+.. c:function:: unsigned int pkgconf_pkg_traverse(pkgconf_client_t *client, pkgconf_pkg_t *root, pkgconf_pkg_traverse_func_t func, void *data, int maxdepth, unsigned int skip_flags)
 
    Walk and resolve the dependency graph up to `maxdepth` levels.
 
@@ -135,6 +127,7 @@ routines.
    :param pkgconf_pkg_traverse_func_t func: A traversal function to call for each resolved node in the dependency graph.
    :param void* data: An opaque pointer to data to be passed to the traversal function.
    :param int maxdepth: The maximum depth to walk the dependency graph for.  -1 means infinite recursion.
+   :param uint skip_flags: Skip over dependency nodes containing the specified flags.  A setting of 0 skips no dependency nodes.
    :return: ``PKGCONF_PKG_ERRF_OK`` on success, else an error code.
    :rtype: unsigned int
 

doc/libpkgconf-queue.rst

@@ -33,11 +33,32 @@ Using the `queue` module functions is the recommended way of working with depend
    :param pkgconf_list_t* list: The dependency resolution queue to release.
    :return: nothing
 
+.. c:function:: void pkgconf_solution_free(pkgconf_client_t *client, pkgconf_pkg_t *world, int maxdepth)
+
+   Removes references to package nodes contained in a solution.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_pkg_t* world: The root for the generated dependency graph.  Should have PKGCONF_PKG_PROPF_VIRTUAL flag.
+   :returns: nothing
+
+.. c:function:: bool pkgconf_queue_solve(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_pkg_t *world, int maxdepth)
+
+   Solves and flattens the dependency graph for the supplied dependency list.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_list_t* list: The list of dependency requests to consider.
+   :param pkgconf_pkg_t* world: The root for the generated dependency graph, provided by the caller.  Should have PKGCONF_PKG_PROPF_VIRTUAL flag.
+   :param int maxdepth: The maximum allowed depth for the dependency resolver.  A depth of -1 means unlimited.
+   :returns: true if the dependency resolver found a solution, otherwise false.
+   :rtype: bool
+
 .. c:function:: void pkgconf_queue_apply(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queue_apply_func_t func, int maxdepth, void *data)
 
    Attempt to compile a dependency resolution queue into a dependency resolution problem, then attempt to solve the problem and
    feed the solution to a callback function if a complete dependency graph is found.
 
+   This function should not be used in new code.  Use pkgconf_queue_solve instead.
+
    :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
    :param pkgconf_list_t* list: The list of dependency requests to consider.
    :param pkgconf_queue_apply_func_t func: The callback function to call if a solution is found by the dependency resolver.

doc/libpkgconf-tuple.rst

@@ -64,13 +64,14 @@ attached to a given client object.
    :return: the value of the variable or ``NULL``
    :rtype: char *
 
-.. c:function:: char *pkgconf_tuple_parse(const pkgconf_client_t *client, pkgconf_list_t *vars, const char *value)
+.. c:function:: char *pkgconf_tuple_parse(const pkgconf_client_t *client, pkgconf_list_t *vars, const char *value, unsigned int flags)
 
    Parse an expression for variable substitution.
 
    :param pkgconf_client_t* client: The pkgconf client object to access.
    :param pkgconf_list_t* list: The variable list to search for variables (along side the global variable list).
    :param char* value: The ``key=value`` string to parse.
+   :param uint flags: Any flags to consider while parsing.
    :return: the variable data with any variables substituted
    :rtype: char *
 

doc/libpkgconf.rst

@@ -11,6 +11,7 @@ libpkgconf - an API for managing `pkg-config` modules
    libpkgconf-dependency
    libpkgconf-fragment
    libpkgconf-path
+   libpkgconf-personality
    libpkgconf-pkg
    libpkgconf-queue
    libpkgconf-tuple

libpkgconf/personality.c

@@ -17,6 +17,13 @@
 #include <libpkgconf/stdinc.h>
 #include <libpkgconf/libpkgconf.h>
 
+/*
+ * !doc
+ *
+ * libpkgconf `personality` module
+ * =========================
+ */
+
 #ifdef _WIN32
 #	define strcasecmp _stricmp
 #endif