From: Emil Velikov <emil.l.velikov@gmail.com>
Date: Sat, 14 Sep 2024 13:05:32 +0000 (+0100)
Subject: docs: annotate the v1 API
X-Git-Tag: v34~362
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ffbbd3f354ac6b1e17033e260174dd5d7a24ab12;p=thirdparty%2Fkmod.git

docs: annotate the v1 API

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

diff --git a/libkmod/libkmod.h b/libkmod/libkmod.h
index bcccbbac..d224e525 100644
--- a/libkmod/libkmod.h
+++ b/libkmod/libkmod.h
@@ -52,6 +52,8 @@ struct kmod_ctx;
  * release the resources of the kmod library context.
  *
  * Returns: a new kmod library context
+ *
+ * Since: 1
  */
 struct kmod_ctx *kmod_new(const char *dirname, const char * const *config_paths);
 
@@ -62,6 +64,8 @@ struct kmod_ctx *kmod_new(const char *dirname, const char * const *config_paths)
  * Take a reference of the kmod library context.
  *
  * Returns: the passed kmod library context
+ *
+ * Since: 1
  */
 struct kmod_ctx *kmod_ref(struct kmod_ctx *ctx);
 
@@ -73,6 +77,8 @@ struct kmod_ctx *kmod_ref(struct kmod_ctx *ctx);
  * reaches zero, the resources of the context will be released.
  *
  * Returns: the passed kmod library context or NULL if it's freed
+ *
+ * Since: 1
  */
 struct kmod_ctx *kmod_unref(struct kmod_ctx *ctx);
 
@@ -91,6 +97,8 @@ struct kmod_ctx *kmod_unref(struct kmod_ctx *ctx);
  * this function will speedup the searches.
  *
  * Returns: 0 on success or < 0 otherwise.
+ *
+ * Since: 1
  */
 int kmod_load_resources(struct kmod_ctx *ctx);
 
@@ -108,6 +116,8 @@ int kmod_load_resources(struct kmod_ctx *ctx);
  * could free the resources by calling kmod_unload_resources().
  *
  * Returns: 0 on success or < 0 otherwise.
+ *
+ * Since: 1
  */
 void kmod_unload_resources(struct kmod_ctx *ctx);
 
@@ -181,6 +191,8 @@ int kmod_dump_index(struct kmod_ctx *ctx, enum kmod_index type, int fd);
  *
  * Set the current logging priority, as defined in syslog.h(0P). The value
  * controls which messages are logged.
+ *
+ * Since: 1
  */
 void kmod_set_log_priority(struct kmod_ctx *ctx, int priority);
 
@@ -191,6 +203,8 @@ void kmod_set_log_priority(struct kmod_ctx *ctx, int priority);
  * Get the current logging priority, as defined in syslog.h(0P).
  *
  * Returns: the current logging priority
+ *
+ * Since: 1
  */
 int kmod_get_log_priority(const struct kmod_ctx *ctx);
 
@@ -203,6 +217,8 @@ int kmod_get_log_priority(const struct kmod_ctx *ctx);
  * The built-in logging writes to stderr. It can be
  * overridden by a custom function, to plug log messages
  * into the user's logging functionality.
+ *
+ * Since: 1
  */
 void kmod_set_log_fn(struct kmod_ctx *ctx,
 			void (*log_fn)(void *log_data,
@@ -217,6 +233,8 @@ void kmod_set_log_fn(struct kmod_ctx *ctx,
  * @userdata: data pointer
  *
  * Store custom @userdata in the library context.
+ *
+ * Since: 1
  */
 void kmod_set_userdata(struct kmod_ctx *ctx, const void *userdata);
 
@@ -228,6 +246,8 @@ void kmod_set_userdata(struct kmod_ctx *ctx, const void *userdata);
  * to access from callbacks.
  *
  * Returns: stored userdata
+ *
+ * Since: 1
  */
 void *kmod_get_userdata(const struct kmod_ctx *ctx);
 
@@ -307,6 +327,8 @@ struct kmod_list *kmod_list_last(const struct kmod_list *list);
  *
  * Returns: node next to @curr or NULL if either this node is the last of or
  * list is empty.
+ *
+ * Since: 1
  */
 struct kmod_list *kmod_list_next(const struct kmod_list *list,
 						const struct kmod_list *curr);
@@ -323,6 +345,8 @@ struct kmod_list *kmod_list_next(const struct kmod_list *list,
  *
  * Returns: node previous to @curr or NULL if either this node is the head of
  * the list or the list is empty.
+ *
+ * Since: 1
  */
 struct kmod_list *kmod_list_prev(const struct kmod_list *list,
 						const struct kmod_list *curr);
@@ -530,6 +554,8 @@ struct kmod_module;
  * Returns: 0 on success or < 0 otherwise. It fails if any of the lookup
  * methods failed, which is basically due to memory allocation fail. If module
  * is not found, it still returns 0, but @list is an empty list.
+ *
+ * Since: 1
  */
 int kmod_module_new_from_lookup(struct kmod_ctx *ctx, const char *given_alias,
 						struct kmod_list **list);
@@ -583,6 +609,8 @@ int kmod_module_new_from_name_lookup(struct kmod_ctx *ctx,
  *
  * Returns: 0 on success or < 0 otherwise. It fails if name is not a valid
  * module name or if memory allocation failed.
+ *
+ * Since: 1
  */
 int kmod_module_new_from_name(struct kmod_ctx *ctx, const char *name,
 						struct kmod_module **mod);
@@ -607,6 +635,8 @@ int kmod_module_new_from_name(struct kmod_ctx *ctx, const char *name,
  *
  * Returns: 0 on success or < 0 otherwise. It fails if file does not exist, if
  * it's not a valid file for a kmod_module or if memory allocation failed.
+ *
+ * Since: 1
  */
 int kmod_module_new_from_path(struct kmod_ctx *ctx, const char *path,
 						struct kmod_module **mod);
@@ -619,6 +649,8 @@ int kmod_module_new_from_path(struct kmod_ctx *ctx, const char *path,
  * Take a reference of the kmod module, incrementing its refcount.
  *
  * Returns: the passed @module with its refcount incremented.
+ *
+ * Since: 1
  */
 struct kmod_module *kmod_module_ref(struct kmod_module *mod);
 
@@ -631,6 +663,8 @@ struct kmod_module *kmod_module_ref(struct kmod_module *mod);
  *
  * Returns: NULL if @mod is NULL or if the module was released. Otherwise it
  * returns the passed @mod with its refcount decremented.
+ *
+ * Since: 1
  */
 struct kmod_module *kmod_module_unref(struct kmod_module *mod);
 
@@ -642,6 +676,8 @@ struct kmod_module *kmod_module_unref(struct kmod_module *mod);
  * taken by the list itself.
  *
  * Returns: 0
+ *
+ * Since: 1
  */
 int kmod_module_unref_list(struct kmod_list *list);
 
@@ -670,6 +706,8 @@ enum kmod_insert {
  *
  * Returns: 0 on success or < 0 on failure. If module is already loaded it
  * returns -EEXIST.
+ *
+ * Since: 1
  */
 int kmod_module_insert_module(struct kmod_module *mod, unsigned int flags,
 							const char *options);
@@ -768,6 +806,8 @@ enum kmod_remove {
  * Remove a module from the kernel.
  *
  * Returns: 0 on success or < 0 on failure.
+ *
+ * Since: 1
  */
 int kmod_module_remove_module(struct kmod_module *mod, unsigned int flags);
 
@@ -783,6 +823,8 @@ int kmod_module_remove_module(struct kmod_module *mod, unsigned int flags);
  *
  * Returns: NULL on failure or the kmod_module contained in this list entry
  * with its refcount incremented.
+ *
+ * Since: 1
  */
 struct kmod_module *kmod_module_get_module(const struct kmod_list *entry);
 
@@ -796,6 +838,8 @@ struct kmod_module *kmod_module_get_module(const struct kmod_list *entry);
  *
  * Returns: NULL on failure. Otherwise it returns a list of kmod modules
  * that can be released by calling kmod_module_unref_list().
+ *
+ * Since: 1
  */
 struct kmod_list *kmod_module_get_dependencies(const struct kmod_module *mod);
 
@@ -881,6 +925,8 @@ int kmod_module_apply_filter(const struct kmod_ctx *ctx,
  *
  * Returns: 0 on success or < 0 otherwise. @output is saved with the updated
  * list.
+ *
+ * Since: 1
  */
 int kmod_module_get_filtered_blacklist(const struct kmod_ctx *ctx,
 					const struct kmod_list *input,
@@ -899,6 +945,8 @@ int kmod_module_get_filtered_blacklist(const struct kmod_ctx *ctx,
  *
  * Returns: a string with all install commands separated by semicolons. This
  * string is owned by @mod, do not free it.
+ *
+ * Since: 1
  */
 const char *kmod_module_get_install_commands(const struct kmod_module *mod);
 
@@ -915,6 +963,8 @@ const char *kmod_module_get_install_commands(const struct kmod_module *mod);
  *
  * Returns: a string with all remove commands separated by semicolons. This
  * string is owned by @mod, do not free it.
+ *
+ * Since: 1
  */
 const char *kmod_module_get_remove_commands(const struct kmod_module *mod);
 
@@ -927,6 +977,8 @@ const char *kmod_module_get_remove_commands(const struct kmod_module *mod);
  * it's always normalized (dashes are replaced with underscores).
  *
  * Returns: the name of this kmod module.
+ *
+ * Since: 1
  */
 const char *kmod_module_get_name(const struct kmod_module *mod);
 
@@ -940,6 +992,8 @@ const char *kmod_module_get_name(const struct kmod_module *mod);
  *
  * Returns: a string with all the options separated by spaces. This string is
  * owned by @mod, do not free it.
+ *
+ * Since: 1
  */
 const char *kmod_module_get_options(const struct kmod_module *mod);
 
@@ -953,6 +1007,8 @@ const char *kmod_module_get_options(const struct kmod_module *mod);
  *
  * Returns: the path of this kmod module or NULL if such information is not
  * available.
+ *
+ * Since: 1
  */
 const char *kmod_module_get_path(const struct kmod_module *mod);
 
@@ -1047,6 +1103,8 @@ void kmod_module_dependency_symbols_free_list(struct kmod_list *list);
  * After use, free the @list by calling kmod_module_section_free_list().
  *
  * Returns: a new list of kmod module sections on success or NULL on failure.
+ *
+ * Since: 1
  */
 struct kmod_list *kmod_module_get_sections(const struct kmod_module *mod);
 
@@ -1058,6 +1116,8 @@ struct kmod_list *kmod_module_get_sections(const struct kmod_module *mod);
  *
  * Returns: the address of this kmod module section on success or ULONG_MAX
  * on failure.
+ *
+ * Since: 1
  */
 unsigned long kmod_module_section_get_address(const struct kmod_list *entry);
 
@@ -1069,6 +1129,8 @@ unsigned long kmod_module_section_get_address(const struct kmod_list *entry);
  *
  * Returns: the name of this kmod module section on success or NULL on
  * failure. The string is owned by the section, do not free it.
+ *
+ * Since: 1
  */
 const char *kmod_module_section_get_name(const struct kmod_list *entry);
 
@@ -1077,6 +1139,8 @@ const char *kmod_module_section_get_name(const struct kmod_list *entry);
  * @list: kmod module section list
  *
  * Release the resources taken by @list
+ *
+ * Since: 1
  */
 void kmod_module_section_free_list(struct kmod_list *list);
 
@@ -1255,6 +1319,8 @@ void kmod_module_info_free_list(struct kmod_list *list);
  * completed.
  *
  * Returns: 0 on success or < 0 on error.
+ *
+ * Since: 1
  */
 int kmod_module_new_from_loaded(struct kmod_ctx *ctx,
 						struct kmod_list **list);
@@ -1287,6 +1353,8 @@ enum kmod_module_initstate {
  *
  * Returns: < 0 on error or module state if module is found in the kernel, valid
  * states are #kmod_module_initstate.
+ *
+ * Since: 1
  */
 int kmod_module_get_initstate(const struct kmod_module *mod);
 
@@ -1298,6 +1366,8 @@ int kmod_module_get_initstate(const struct kmod_module *mod);
  *
  * Returns: the string associated to the @state. This string is statically
  * allocated, do not free it.
+ *
+ * Since: 1
  */
 const char *kmod_module_initstate_str(enum kmod_module_initstate state);
 
@@ -1311,6 +1381,8 @@ const char *kmod_module_initstate_str(enum kmod_module_initstate state);
  * module to get its size.
  *
  * Returns: the size of this kmod module.
+ *
+ * Since: 1
  */
 long kmod_module_get_size(const struct kmod_module *mod);
 
@@ -1322,6 +1394,8 @@ long kmod_module_get_size(const struct kmod_module *mod);
  * /sys filesystem.
  *
  * Returns: the reference count on success or < 0 on failure.
+ *
+ * Since: 1
  */
 int kmod_module_get_refcnt(const struct kmod_module *mod);
 
@@ -1333,6 +1407,8 @@ int kmod_module_get_refcnt(const struct kmod_module *mod);
  * 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.
+ *
+ * Since: 1
  */
 struct kmod_list *kmod_module_get_holders(const struct kmod_module *mod);