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@xxxxxxxxxx>
---
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
_______________________________________________
Libosinfo mailing list
Libosinfo@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libosinfo
