[Libosinfo] [libosinfo PATCH 06/20] Add "Since: 0.2.1" to the documentation

Fabiano Fidêncio fidencio at redhat.com
Mon Jul 15 13:01:44 UTC 2019


Let's add the "Since: ..." information as part of the function's
documentation. It helps developers reading our docs to easily figure out
when a function has been introduced.

Together with this change, documentation has been added to the functions
missing them.

Signed-off-by: Fabiano Fidêncio <fidencio at redhat.com>
---
 osinfo/osinfo_device.c               |  8 ++++
 osinfo/osinfo_entity.c               | 59 ++++++++++++++++++++++++++++
 osinfo/osinfo_install_config_param.c |  4 ++
 osinfo/osinfo_install_script.c       | 10 +++--
 osinfo/osinfo_media.c                |  2 +
 5 files changed, 80 insertions(+), 3 deletions(-)

diff --git a/osinfo/osinfo_device.c b/osinfo/osinfo_device.c
index 6de3d2c..529a600 100644
--- a/osinfo/osinfo_device.c
+++ b/osinfo/osinfo_device.c
@@ -116,6 +116,14 @@ const gchar *osinfo_device_get_name(OsinfoDevice *dev)
     return osinfo_entity_get_param_value(OSINFO_ENTITY(dev), OSINFO_DEVICE_PROP_NAME);
 }
 
+/**
+ * osinfo_device_get_subsystem:
+ * @dev: the device
+ *
+ * Returns: the value of the device's subsystem.
+ *
+ * Since: 0.2.1
+ */
 const gchar *osinfo_device_get_subsystem(OsinfoDevice *dev)
 {
     return osinfo_entity_get_param_value(OSINFO_ENTITY(dev), OSINFO_DEVICE_PROP_SUBSYSTEM);
diff --git a/osinfo/osinfo_entity.c b/osinfo/osinfo_entity.c
index f634d78..86d1c4a 100644
--- a/osinfo/osinfo_entity.c
+++ b/osinfo/osinfo_entity.c
@@ -204,6 +204,18 @@ void osinfo_entity_set_param_boolean(OsinfoEntity *entity, const gchar *key, gbo
     osinfo_entity_set_param(entity, key, value ? "true" : "false");
 }
 
+/**
+ * osinfo_entity_set_param_int64:
+ * @entity: an #OsinfoEntity containing the parameters
+ * @key: the name of the key
+ * @value: the int64 value to be associated with that key
+ *
+ * Sets a new parameter against the entity. If the key already
+ * has a value associated with it, the existing value will be
+ * cleared.
+ *
+ * Since: 0.2.1
+ */
 void osinfo_entity_set_param_int64(OsinfoEntity *entity, const gchar *key, gint64 value)
 {
     gchar *str;
@@ -363,6 +375,23 @@ gboolean osinfo_entity_get_param_value_boolean(OsinfoEntity *entity, const gchar
     return value && str_to_bool(value);
 }
 
+/**
+ * osinfo_entity_get_param_value_boolean_with_default:
+ * @entity: an #OsinfoEntity containing the parameters
+ * @key: the name of the key
+ * @default_value: the value to be returned in case there's no value
+ *                 associated with the @key
+ *
+ * Retrieve the parameter value associated with a named key as a
+ * boolean. If multiple values are stored against the key, only the
+ * first value is returned. If no value is associated, @default_value
+ * is returned.
+ *
+ * Returns: the value associated with the key as a boolean, or
+ * @default_value
+ *
+ * Since: 0.2.1
+ */
 gboolean osinfo_entity_get_param_value_boolean_with_default(OsinfoEntity *entity,
                                                             const char *key,
                                                             gboolean default_value)
@@ -376,12 +405,42 @@ gboolean osinfo_entity_get_param_value_boolean_with_default(OsinfoEntity *entity
         return str_to_bool(value);
 }
 
+/**
+ * osinfo_entity_get_param_value_int64:
+ * @entity: an #OsinfoEntity containing the parameters
+ * @key: the name of the key
+ *
+ * Retrieve the parameter value associated with a named key as an
+ * int64. If multiple values are stored against the key, only the
+ * first value is returned. If no value is associated, -1 is returned.
+ *
+ * Returns: the value associated with the key as an int64, or -1.
+ *
+ * Since: 0.2.1
+ */
 gint64 osinfo_entity_get_param_value_int64(OsinfoEntity *entity,
                                            const gchar *key)
 {
     return osinfo_entity_get_param_value_int64_with_default(entity, key, -1);
 }
 
+/**
+ * osinfo_entity_get_param_value_int64_with_default:
+ * @entity: an #OsinfoEntity containing the parameters
+ * @key: the name of the key
+ * @default_value: the value to be returned in case there's no value
+ *                 associated with the @key
+ *
+ * Retrieve the parameter value associated with a named key as an
+ * int64. If multiple values are stored against the key, only the
+ * first value is returned. If no value is associated, @default_value
+ * is returned.
+ *
+ * Returns: the value associated with the key as an int64, or
+ * @default_value
+ *
+ * Since: 0.2.1
+ */
 gint64 osinfo_entity_get_param_value_int64_with_default(OsinfoEntity *entity,
                                                         const gchar *key,
                                                         gint64 default_value)
diff --git a/osinfo/osinfo_install_config_param.c b/osinfo/osinfo_install_config_param.c
index 187569f..ab854b3 100644
--- a/osinfo/osinfo_install_config_param.c
+++ b/osinfo/osinfo_install_config_param.c
@@ -253,6 +253,8 @@ OsinfoInstallConfigParamPolicy osinfo_install_config_param_get_policy(OsinfoInst
  *
  * Returns: (transfer none): TRUE if the config_param is required.
  *                           FALSE otherwise.
+ *
+ * Since: 0.2.1
  */
 gboolean osinfo_install_config_param_is_required(OsinfoInstallConfigParam *config_param)
 {
@@ -266,6 +268,8 @@ gboolean osinfo_install_config_param_is_required(OsinfoInstallConfigParam *confi
  *
  * Returns: (transfer none): TRUE if the config_param is optional.
  *                           FALSE otherwise.
+ *
+ * Since: 0.2.1
  */
 gboolean osinfo_install_config_param_is_optional(OsinfoInstallConfigParam *config_param)
 {
diff --git a/osinfo/osinfo_install_script.c b/osinfo/osinfo_install_script.c
index b9714e3..6d68f1e 100644
--- a/osinfo/osinfo_install_script.c
+++ b/osinfo/osinfo_install_script.c
@@ -383,14 +383,16 @@ OsinfoInstallConfigParamList *osinfo_install_script_get_config_params(OsinfoInst
  *
  * Returns: (transfer full): the sought config param, if exists.
  *                           NULL otherwise.
+ *
+ * This code assumes that the 'id' and 'name' entity properties are
+ * the same.
+ *
+ * Since: 0.2.1
  */
 OsinfoInstallConfigParam *
 osinfo_install_script_get_config_param(OsinfoInstallScript *script,
                                        const gchar *name)
 {
-    /* NB: this code assumes that the 'id' and 'name' entity properties
-     * are the same
-     */
     OsinfoInstallConfigParam *param;
     OsinfoList *l = OSINFO_LIST(script->priv->config_params);
     param = OSINFO_INSTALL_CONFIG_PARAM(osinfo_list_find_by_id(l, name));
@@ -588,6 +590,8 @@ const gchar *osinfo_install_script_get_output_prefix(OsinfoInstallScript *script
  * particular name to work.
  *
  * Returns: (transfer none): the expected script filename
+ *
+ * Since: 0.2.1
  */
 const gchar *osinfo_install_script_get_expected_filename(OsinfoInstallScript *script)
 {
diff --git a/osinfo/osinfo_media.c b/osinfo/osinfo_media.c
index 9592f04..86d9696 100644
--- a/osinfo/osinfo_media.c
+++ b/osinfo/osinfo_media.c
@@ -1598,6 +1598,8 @@ gboolean osinfo_media_get_live(OsinfoMedia *media)
  *
  * Returns: (transfer none): the number of installer reboots or -1 if media is
  * not an installer
+ *
+ * Since: 0.2.1
  */
 gint osinfo_media_get_installer_reboots(OsinfoMedia *media)
 {
-- 
2.21.0




More information about the Libosinfo mailing list