libkmod/docs: move libkmod-loaded section to the header

In part to ease my life as I'm going through (shortly) and updating the
log. In part so that developers how don't install the gtk-doc html
pages, still have the information at hand.

While here, sort the API akin to the HTML documentation.

Signed-off-by: Emil Velikov <emil.l.velikov@gmail.com>
Link: https://github.com/kmod-project/kmod/pull/94
Signed-off-by: Lucas De Marchi <lucas.de.marchi@gmail.com>

diff --git a/libkmod/libkmod-module.c b/libkmod/libkmod-module.c
index 2d3e47a9cf8eb0df6c3925d38f11db9695f2b5f5..d4cde1efa1e2bbb3b0e34ce0a24447f50f16c16e 100644 (file)
--- a/libkmod/libkmod-module.c
+++ b/libkmod/libkmod-module.c
@@ -1405,34 +1405,6 @@ void kmod_module_set_remove_commands(struct kmod_module *mod, const char *cmd)
        mod->remove_commands = cmd;
 }
 
-/**
- * SECTION:libkmod-loaded
- * @short_description: currently loaded modules
- *
- * Information about currently loaded modules, as reported by Linux kernel.
- * These information are not cached by libkmod and are always read from /sys
- * and /proc/modules.
- */
-
-/**
- * kmod_module_new_from_loaded:
- * @ctx: kmod library context
- * @list: where to save the list of loaded modules
- *
- * Create a new list of kmod modules with all modules currently loaded in
- * kernel. It uses /proc/modules to get the names of loaded modules and to
- * create kmod modules by calling kmod_module_new_from_name() in each of them.
- * They are put in @list in no particular order.
- *
- * The initial refcount is 1, and needs to be decremented to release the
- * resources of the kmod_module. The returned @list must be released by
- * calling kmod_module_unref_list(). Since libkmod keeps track of all
- * kmod_modules created, they are all released upon @ctx destruction too. Do
- * not unref @ctx before all the desired operations with the returned list are
- * completed.
- *
- * Returns: 0 on success or < 0 on error.
- */
 KMOD_EXPORT int kmod_module_new_from_loaded(struct kmod_ctx *ctx,
                                                struct kmod_list **list)
 {
@@ -1482,15 +1454,6 @@ eat_line:
        return 0;
 }
 
-/**
- * kmod_module_initstate_str:
- * @state: the state as returned by kmod_module_get_initstate()
- *
- * Translate a initstate to a string.
- *
- * Returns: the string associated to the @state. This string is statically
- * allocated, do not free it.
- */
 KMOD_EXPORT const char *kmod_module_initstate_str(enum kmod_module_initstate state)
 {
        switch (state) {
@@ -1507,19 +1470,6 @@ KMOD_EXPORT const char *kmod_module_initstate_str(enum kmod_module_initstate sta
        }
 }
 
-/**
- * kmod_module_get_initstate:
- * @mod: kmod module
- *
- * Get the initstate of this @mod, as returned by Linux Kernel, by reading
- * /sys filesystem.
- *
- * Returns: < 0 on error or module state if module is found in kernel, valid states are
- * KMOD_MODULE_BUILTIN: module is builtin;
- * KMOD_MODULE_LIVE: module is live in kernel;
- * KMOD_MODULE_COMING: module is being loaded;
- * KMOD_MODULE_GOING: module is being unloaded.
- */
 KMOD_EXPORT int kmod_module_get_initstate(const struct kmod_module *mod)
 {
        char path[PATH_MAX], buf[32];
@@ -1576,17 +1526,6 @@ KMOD_EXPORT int kmod_module_get_initstate(const struct kmod_module *mod)
        return -EINVAL;
 }
 
-/**
- * kmod_module_get_size:
- * @mod: kmod module
- *
- * Get the size of this kmod module as returned by Linux kernel. If supported,
- * the size is read from the coresize attribute in /sys/module. For older
- * kernels, this falls back on /proc/modules and searches for the specified
- * module to get its size.
- *
- * Returns: the size of this kmod module.
- */
 KMOD_EXPORT long kmod_module_get_size(const struct kmod_module *mod)
 {
        FILE *fp;
@@ -1662,15 +1601,6 @@ done:
        return size;
 }
 
-/**
- * kmod_module_get_refcnt:
- * @mod: kmod module
- *
- * Get the ref count of this @mod, as returned by Linux Kernel, by reading
- * /sys filesystem.
- *
- * Returns: the reference count on success or < 0 on failure.
- */
 KMOD_EXPORT int kmod_module_get_refcnt(const struct kmod_module *mod)
 {
        char path[PATH_MAX];
@@ -1700,15 +1630,6 @@ KMOD_EXPORT int kmod_module_get_refcnt(const struct kmod_module *mod)
        return (int)refcnt;
 }
 
-/**
- * kmod_module_get_holders:
- * @mod: kmod module
- *
- * Get a list of kmod modules that are holding this @mod, as returned by Linux
- * Kernel. After use, free the @list by calling kmod_module_unref_list().
- *
- * Returns: a new list of kmod modules on success or NULL on failure.
- */
 KMOD_EXPORT struct kmod_list *kmod_module_get_holders(const struct kmod_module *mod)
 {
        char dname[PATH_MAX];

diff --git a/libkmod/libkmod.h b/libkmod/libkmod.h
index 3a699914d002a4babe9eceef71858ddb7a050a3e..055cfdcd503fbdae5485fe7c6e9423344cce6218 100644 (file)
--- a/libkmod/libkmod.h
+++ b/libkmod/libkmod.h
@@ -1187,6 +1187,35 @@ enum kmod_symbol_bind {
 };
 
 
+
+/**
+ * SECTION:libkmod-loaded
+ * @short_description: currently loaded modules
+ *
+ * Information about currently loaded modules, as reported by Linux kernel.
+ * These information are not cached by libkmod and are always read from /sys
+ * and /proc/modules.
+ */
+
+/**
+ * kmod_module_new_from_loaded:
+ * @ctx: kmod library context
+ * @list: where to save the list of loaded modules
+ *
+ * Create a new list of kmod modules with all modules currently loaded in
+ * kernel. It uses /proc/modules to get the names of loaded modules and to
+ * create kmod modules by calling kmod_module_new_from_name() in each of them.
+ * They are put in @list in no particular order.
+ *
+ * The initial refcount is 1, and needs to be decremented to release the
+ * resources of the kmod_module. The returned @list must be released by
+ * calling kmod_module_unref_list(). Since libkmod keeps track of all
+ * kmod_modules created, they are all released upon @ctx destruction too. Do
+ * not unref @ctx before all the desired operations with the returned list are
+ * completed.
+ *
+ * Returns: 0 on success or < 0 on error.
+ */
 int kmod_module_new_from_loaded(struct kmod_ctx *ctx,
                                                struct kmod_list **list);
 
@@ -1203,13 +1232,67 @@ enum kmod_module_initstate {
        /* Padding to make sure enum is not mapped to char */
        _KMOD_MODULE_PAD = 1U << 31,
 };
-const char *kmod_module_initstate_str(enum kmod_module_initstate state);
+
+/**
+ * kmod_module_get_initstate:
+ * @mod: kmod module
+ *
+ * Get the initstate of this @mod, as returned by Linux Kernel, by reading
+ * /sys filesystem.
+ *
+ * Returns: < 0 on error or module state if module is found in kernel, valid states are
+ * KMOD_MODULE_BUILTIN: module is builtin;
+ * KMOD_MODULE_LIVE: module is live in kernel;
+ * KMOD_MODULE_COMING: module is being loaded;
+ * KMOD_MODULE_GOING: module is being unloaded.
+ */
 int kmod_module_get_initstate(const struct kmod_module *mod);
+
+/**
+ * kmod_module_initstate_str:
+ * @state: the state as returned by kmod_module_get_initstate()
+ *
+ * Translate a initstate to a string.
+ *
+ * Returns: the string associated to the @state. This string is statically
+ * allocated, do not free it.
+ */
+const char *kmod_module_initstate_str(enum kmod_module_initstate state);
+
+/**
+ * kmod_module_get_size:
+ * @mod: kmod module
+ *
+ * Get the size of this kmod module as returned by Linux kernel. If supported,
+ * the size is read from the coresize attribute in /sys/module. For older
+ * kernels, this falls back on /proc/modules and searches for the specified
+ * module to get its size.
+ *
+ * Returns: the size of this kmod module.
+ */
 long kmod_module_get_size(const struct kmod_module *mod);
-int kmod_module_get_refcnt(const struct kmod_module *mod);
-struct kmod_list *kmod_module_get_holders(const struct kmod_module *mod);
 
+/**
+ * kmod_module_get_refcnt:
+ * @mod: kmod module
+ *
+ * Get the ref count of this @mod, as returned by Linux Kernel, by reading
+ * /sys filesystem.
+ *
+ * Returns: the reference count on success or < 0 on failure.
+ */
+int kmod_module_get_refcnt(const struct kmod_module *mod);
 
+/**
+ * kmod_module_get_holders:
+ * @mod: kmod module
+ *
+ * Get a list of kmod modules that are holding this @mod, as returned by Linux
+ * Kernel. After use, free the @list by calling kmod_module_unref_list().
+ *
+ * Returns: a new list of kmod modules on success or NULL on failure.
+ */
+struct kmod_list *kmod_module_get_holders(const struct kmod_module *mod);
 
 #ifdef __cplusplus
 } /* extern "C" */