Update documentation with recent changes

libkmod/docs/libkmod-docs.xml

@@ -14,6 +14,7 @@
     <title>libkmod</title>
     <xi:include href="xml/libkmod.xml"/>
     <xi:include href="xml/libkmod-list.xml"/>
+    <xi:include href="xml/libkmod-config.xml"/>
     <xi:include href="xml/libkmod-module.xml"/>
     <xi:include href="xml/libkmod-loaded.xml"/>
 

libkmod/docs/libkmod-sections.txt

@@ -26,6 +26,21 @@ kmod_list_next
 kmod_list_prev
 </SECTION>
 
+<SECTION>
+<FILE>libkmod-config</FILE>
+kmod_config_iter
+kmod_config_get_blacklists
+kmod_config_get_install_commands
+kmod_config_get_remove_commands
+kmod_config_get_aliases
+kmod_config_get_options
+kmod_config_get_softdeps
+kmod_config_iter_get_key
+kmod_config_iter_get_value
+kmod_config_iter_next
+kmod_config_iter_free_iter
+</SECTION>
+
 <SECTION>
 <FILE>libkmod-module</FILE>
 kmod_module

libkmod/libkmod-config.c

@@ -986,6 +986,23 @@ static struct kmod_config_iter *kmod_config_iter_new(const struct kmod_ctx* ctx,
 	return iter;
 }
 
+/**
+ * SECTION:libkmod-config
+ * @short_description: retrieve current libkmod configuration
+ */
+
+/**
+ * kmod_config_get_blacklists:
+ * @ctx: kmod library context
+ *
+ * Retrieve an iterator to deal with the blacklist maintained inside the
+ * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and
+ * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must
+ * be made to initialize the iterator and check if it's valid.
+ *
+ * Returns: a new iterator over the blacklists or %NULL on failure. Free it
+ * with kmod_config_iter_free_iter().
+ */
 KMOD_EXPORT struct kmod_config_iter *kmod_config_get_blacklists(const struct kmod_ctx *ctx)
 {
 	if (ctx == NULL)
@@ -994,6 +1011,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_blacklists(const struct kmo
 	return kmod_config_iter_new(ctx, CONFIG_TYPE_BLACKLIST);
 }
 
+/**
+ * kmod_config_get_install_commands:
+ * @ctx: kmod library context
+ *
+ * Retrieve an iterator to deal with the install commands maintained inside the
+ * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and
+ * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must
+ * be made to initialize the iterator and check if it's valid.
+ *
+ * Returns: a new iterator over the install commands or %NULL on failure. Free
+ * it with kmod_config_iter_free_iter().
+ */
 KMOD_EXPORT struct kmod_config_iter *kmod_config_get_install_commands(const struct kmod_ctx *ctx)
 {
 	if (ctx == NULL)
@@ -1002,6 +1031,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_install_commands(const stru
 	return kmod_config_iter_new(ctx, CONFIG_TYPE_INSTALL);
 }
 
+/**
+ * kmod_config_get_remove_commands:
+ * @ctx: kmod library context
+ *
+ * Retrieve an iterator to deal with the remove commands maintained inside the
+ * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and
+ * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must
+ * be made to initialize the iterator and check if it's valid.
+ *
+ * Returns: a new iterator over the remove commands or %NULL on failure. Free
+ * it with kmod_config_iter_free_iter().
+ */
 KMOD_EXPORT struct kmod_config_iter *kmod_config_get_remove_commands(const struct kmod_ctx *ctx)
 {
 	if (ctx == NULL)
@@ -1010,6 +1051,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_remove_commands(const struc
 	return kmod_config_iter_new(ctx, CONFIG_TYPE_REMOVE);
 }
 
+/**
+ * kmod_config_get_aliases:
+ * @ctx: kmod library context
+ *
+ * Retrieve an iterator to deal with the aliases maintained inside the
+ * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and
+ * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must
+ * be made to initialize the iterator and check if it's valid.
+ *
+ * Returns: a new iterator over the aliases or %NULL on failure. Free it with
+ * kmod_config_iter_free_iter().
+ */
 KMOD_EXPORT struct kmod_config_iter *kmod_config_get_aliases(const struct kmod_ctx *ctx)
 {
 	if (ctx == NULL)
@@ -1018,6 +1071,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_aliases(const struct kmod_c
 	return kmod_config_iter_new(ctx, CONFIG_TYPE_ALIAS);
 }
 
+/**
+ * kmod_config_get_options:
+ * @ctx: kmod library context
+ *
+ * Retrieve an iterator to deal with the options maintained inside the
+ * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and
+ * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must
+ * be made to initialize the iterator and check if it's valid.
+ *
+ * Returns: a new iterator over the options or %NULL on failure. Free it with
+ * kmod_config_iter_free_iter().
+ */
 KMOD_EXPORT struct kmod_config_iter *kmod_config_get_options(const struct kmod_ctx *ctx)
 {
 	if (ctx == NULL)
@@ -1026,6 +1091,18 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_options(const struct kmod_c
 	return kmod_config_iter_new(ctx, CONFIG_TYPE_OPTION);
 }
 
+/**
+ * kmod_config_get_softdeps:
+ * @ctx: kmod library context
+ *
+ * Retrieve an iterator to deal with the softdeps maintained inside the
+ * library. See kmod_config_iter_get_key(), kmod_config_iter_get_value() and
+ * kmod_config_iter_next(). At least one call to kmod_config_iter_next() must
+ * be made to initialize the iterator and check if it's valid.
+ *
+ * Returns: a new iterator over the softdeps or %NULL on failure. Free it with
+ * kmod_config_iter_free_iter().
+ */
 KMOD_EXPORT struct kmod_config_iter *kmod_config_get_softdeps(const struct kmod_ctx *ctx)
 {
 	if (ctx == NULL)
@@ -1034,6 +1111,16 @@ KMOD_EXPORT struct kmod_config_iter *kmod_config_get_softdeps(const struct kmod_
 	return kmod_config_iter_new(ctx, CONFIG_TYPE_SOFTDEP);
 }
 
+/**
+ * kmod_config_iter_get_key:
+ * @iter: iterator over a certain configuration
+ *
+ * When using a new allocated iterator, user must perform a call to
+ * kmod_config_iter_next() to initialize iterator's position and check if it's
+ * valid.
+ *
+ * Returns: the key of the current configuration pointed by @iter.
+ */
 KMOD_EXPORT const char *kmod_config_iter_get_key(const struct kmod_config_iter *iter)
 {
 	if (iter == NULL || iter->curr == NULL)
@@ -1042,6 +1129,16 @@ KMOD_EXPORT const char *kmod_config_iter_get_key(const struct kmod_config_iter *
 	return iter->get_key(iter->curr);
 }
 
+/**
+ * kmod_config_iter_get_value:
+ * @iter: iterator over a certain configuration
+ *
+ * When using a new allocated iterator, user must perform a call to
+ * kmod_config_iter_next() to initialize iterator's position and check if it's
+ * valid.
+ *
+ * Returns: the value of the current configuration pointed by @iter.
+ */
 KMOD_EXPORT const char *kmod_config_iter_get_value(const struct kmod_config_iter *iter)
 {
 	const char *s;
@@ -1063,6 +1160,18 @@ KMOD_EXPORT const char *kmod_config_iter_get_value(const struct kmod_config_iter
 	return s;
 }
 
+/**
+ * kmod_config_iter_next:
+ * @iter: iterator over a certain configuration
+ *
+ * Make @iter point to the next item of a certain configuration. It's an
+ * automatically recycling iterator. When it reaches the end, false is
+ * returned; then if user wants to iterate again, it's sufficient to call this
+ * function once more.
+ *
+ * Returns: true if next position of @iter is valid or false if its end is
+ * reached.
+ */
 KMOD_EXPORT bool kmod_config_iter_next(struct kmod_config_iter *iter)
 {
 	if (iter == NULL)
@@ -1078,6 +1187,12 @@ KMOD_EXPORT bool kmod_config_iter_next(struct kmod_config_iter *iter)
 	return iter->curr != NULL;
 }
 
+/**
+ * kmod_config_iter_free_iter:
+ * @iter: iterator over a certain configuration
+ *
+ * Free resources used by the iterator.
+ */
 KMOD_EXPORT void kmod_config_iter_free_iter(struct kmod_config_iter *iter)
 {
 	free(iter->data);

libkmod/libkmod.c

@@ -183,13 +183,16 @@ static char *get_kernel_release(const char *dirname)
 /**
  * kmod_new:
  * @dirname: what to consider as linux module's directory, if NULL
- *           defaults to $rootprefix/lib/modules/`uname -r`.
+ *           defaults to $rootprefix/lib/modules/`uname -r`. If it's relative,
+ *           it's treated as relative to current the current working
+ *           directory. Otherwise, give an absolute dirname.
  * @config_paths: ordered array of paths (directories or files) where
  *                to load from user-defined configuration parameters such as
  *                alias, blacklists, commands (install, remove). If
  *                NULL defaults to /run/modprobe.d, /etc/modprobe.d and
- *                $rootprefix/lib/modprobe.d. Give an empty vector if configuration should
- *                not be read. This array must be null terminated.
+ *                $rootprefix/lib/modprobe.d. Give an empty vector if
+ *                configuration should not be read. This array must be null
+ *                terminated.
  *
  * Create kmod library context. This reads the kmod configuration
  * and fills in the default values.