[Libosinfo] [libosinfo PATCH 07/20] Add "Since: 0.2.2" to the documentation
Fabiano Fidêncio
fidencio at redhat.com
Mon Jul 15 13:01:45 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_avatar_format.c | 8 ++++++++
osinfo/osinfo_device_driver.c | 10 ++++++++++
osinfo/osinfo_device_driverlist.c | 2 ++
osinfo/osinfo_entity.c | 30 ++++++++++++++++++++++++++++
osinfo/osinfo_install_config.c | 30 ++++++++++++++++++++++++++++
osinfo/osinfo_install_config_param.h | 1 +
osinfo/osinfo_install_script.c | 30 ++++++++++++++++++++++++++++
osinfo/osinfo_list.c | 8 ++++++++
osinfo/osinfo_os.c | 11 ++++++++++
9 files changed, 130 insertions(+)
diff --git a/osinfo/osinfo_avatar_format.c b/osinfo/osinfo_avatar_format.c
index 1fe4294..ade4d09 100644
--- a/osinfo/osinfo_avatar_format.c
+++ b/osinfo/osinfo_avatar_format.c
@@ -187,6 +187,8 @@ osinfo_avatar_format_new(void)
* @avatar: the avatar info
*
* Returns: (transfer container) (element-type utf8): the required mime-types of the avatar.
+ *
+ * Since: 0.2.2
*/
GList *
osinfo_avatar_format_get_mime_types(OsinfoAvatarFormat *avatar)
@@ -200,6 +202,8 @@ osinfo_avatar_format_get_mime_types(OsinfoAvatarFormat *avatar)
* @avatar: the avatar info
*
* Returns: the required width (in pixels) of the avatar, or -1.
+ *
+ * Since: 0.2.2
*/
gint
osinfo_avatar_format_get_width(OsinfoAvatarFormat *avatar)
@@ -213,6 +217,8 @@ osinfo_avatar_format_get_width(OsinfoAvatarFormat *avatar)
* @avatar: the avatar info
*
* Returns: the required height (in pixels) of the avatar, or -1.
+ *
+ * Since: 0.2.2
*/
gint
osinfo_avatar_format_get_height(OsinfoAvatarFormat *avatar)
@@ -226,6 +232,8 @@ osinfo_avatar_format_get_height(OsinfoAvatarFormat *avatar)
* @avatar: the avatar info
*
* Returns: Whether alpha channel is supported in the avatar.
+ *
+ * Since: 0.2.2
*/
gboolean
osinfo_avatar_format_get_alpha(OsinfoAvatarFormat *avatar)
diff --git a/osinfo/osinfo_device_driver.c b/osinfo/osinfo_device_driver.c
index dc9ae41..04ab5d8 100644
--- a/osinfo/osinfo_device_driver.c
+++ b/osinfo/osinfo_device_driver.c
@@ -98,6 +98,8 @@ OsinfoDeviceDriver *osinfo_device_driver_new(const gchar *id)
* Retrieves the target hardware architecture of @driver.
*
* Returns: (transfer none): the hardware architecture.
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_device_driver_get_architecture(OsinfoDeviceDriver *driver)
{
@@ -112,6 +114,8 @@ const gchar *osinfo_device_driver_get_architecture(OsinfoDeviceDriver *driver)
* Retrieves the location of the @driver as a URL.
*
* Returns: (transfer none): the location of the driver.
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_device_driver_get_location(OsinfoDeviceDriver *driver)
{
@@ -127,6 +131,8 @@ const gchar *osinfo_device_driver_get_location(OsinfoDeviceDriver *driver)
* #osinfo_device_driver_get_location.
*
* Returns: (transfer container) (element-type utf8): The list of driver files.
+ *
+ * Since: 0.2.2
*/
GList *osinfo_device_driver_get_files(OsinfoDeviceDriver *driver)
{
@@ -139,6 +145,8 @@ GList *osinfo_device_driver_get_files(OsinfoDeviceDriver *driver)
* @driver: an #OsinfoDeviceDriver instance
*
* Returns: TRUE if @driver is pre-installable, FALSE otherwise.
+ *
+ * Since: 0.2.2
*/
gboolean osinfo_device_driver_get_pre_installable(OsinfoDeviceDriver *driver)
{
@@ -152,6 +160,8 @@ gboolean osinfo_device_driver_get_pre_installable(OsinfoDeviceDriver *driver)
* @driver: an #OsinfoDeviceDriver instance
*
* Returns: (transfer none): The list of devices supported by this driver.
+ *
+ * Since: 0.2.2
*/
OsinfoDeviceList *osinfo_device_driver_get_devices(OsinfoDeviceDriver *driver)
{
diff --git a/osinfo/osinfo_device_driverlist.c b/osinfo/osinfo_device_driverlist.c
index 1127709..61c5664 100644
--- a/osinfo/osinfo_device_driverlist.c
+++ b/osinfo/osinfo_device_driverlist.c
@@ -75,6 +75,8 @@ osinfo_device_driverlist_init(OsinfoDeviceDriverList *list)
* Construct a new device driver list that is initially empty.
*
* Returns: (transfer full): an empty device driver list
+ *
+ * Since: 0.2.2
*/
OsinfoDeviceDriverList *osinfo_device_driverlist_new(void)
{
diff --git a/osinfo/osinfo_entity.c b/osinfo/osinfo_entity.c
index 86d1c4a..f35b6ec 100644
--- a/osinfo/osinfo_entity.c
+++ b/osinfo/osinfo_entity.c
@@ -225,6 +225,19 @@ void osinfo_entity_set_param_int64(OsinfoEntity *entity, const gchar *key, gint6
g_free(str);
}
+/**
+ * osinfo_entity_set_param_enum:
+ * @entity: an #OsinfoEntity containing the parameters
+ * @key: the name of the key
+ * @value: the enum value to be associated with that key
+ * @enum_type: the enum type
+ *
+ * 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.2
+ */
void osinfo_entity_set_param_enum(OsinfoEntity *entity, const gchar *key, gint value, GType enum_type)
{
GEnumClass *enum_class;
@@ -455,6 +468,23 @@ gint64 osinfo_entity_get_param_value_int64_with_default(OsinfoEntity *entity,
return g_ascii_strtoll(str, NULL, 0);
}
+/**
+ * osinfo_entity_get_param_value_enum:
+ * @entity: an #OsinfoEntity containing the parameters
+ * @key: the name of the key
+ * @enum_type: the enum type
+ * @default_value: the default value to be used, in case there's
+ * no value associated with the key
+ *
+ * Retrieve the parameter value associated with a named key as an
+ * enum value. If multiple values are stored against the key, only
+ * the first value is returned. If no value is associated, the
+ * @default_value is returned.
+ *
+ * Returns: the enum value associated with the key, or @default_value.
+ *
+ * Since: 0.2.2
+ */
gint osinfo_entity_get_param_value_enum(OsinfoEntity *entity,
const char *key,
GType enum_type,
diff --git a/osinfo/osinfo_install_config.c b/osinfo/osinfo_install_config.c
index e8a181e..05eff36 100644
--- a/osinfo/osinfo_install_config.c
+++ b/osinfo/osinfo_install_config.c
@@ -573,6 +573,8 @@ const gchar *osinfo_install_config_get_hostname(OsinfoInstallConfig *config)
* does the script expects this string to be in. In case of
* #OSINFO_PATH_FORMAT_UNIX unix device node names are expected, e.g "/dev/fd0".
* In case of #OSINFO_PATH_FORMAT_DOS drive letters are expected, e.g "A".
+ *
+ * Since: 0.2.2
*/
void osinfo_install_config_set_target_disk(OsinfoInstallConfig *config,
const gchar *disk)
@@ -588,6 +590,8 @@ void osinfo_install_config_set_target_disk(OsinfoInstallConfig *config,
*
* Returns: The value of #OSINFO_INSTALL_CONFIG_PROP_TARGET_DISK parameter,
* or NULL.
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_install_config_get_target_disk(OsinfoInstallConfig *config)
{
@@ -604,6 +608,8 @@ const gchar *osinfo_install_config_get_target_disk(OsinfoInstallConfig *config)
*
* Please read documentation on #osinfo_install_config_set_target_disk() for
* explanation on the format of @disk string.
+ *
+ * Since: 0.2.2
*/
void osinfo_install_config_set_script_disk(OsinfoInstallConfig *config,
const gchar *disk)
@@ -619,6 +625,8 @@ void osinfo_install_config_set_script_disk(OsinfoInstallConfig *config,
*
* Returns: The value of #OSINFO_INSTALL_CONFIG_PROP_SCRIPT_DISK parameter,
* or NULL.
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_install_config_get_script_disk(OsinfoInstallConfig *config)
{
@@ -640,6 +648,8 @@ const gchar *osinfo_install_config_get_script_disk(OsinfoInstallConfig *config)
*
* Also note that in case of #OSINFO_PATH_FORMAT_DOS, the drive/disk letter
* and the leading ':' must not be included in the path.
+ *
+ * Since: 0.2.2
*/
void osinfo_install_config_set_avatar_location(OsinfoInstallConfig *config,
const gchar *location)
@@ -655,6 +665,8 @@ void osinfo_install_config_set_avatar_location(OsinfoInstallConfig *config,
*
* Returns: The value of #OSINFO_INSTALL_CONFIG_PROP_AVATAR_LOCATION parameter,
* or NULL.
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_install_config_get_avatar_location(OsinfoInstallConfig *config)
{
@@ -671,6 +683,8 @@ const gchar *osinfo_install_config_get_avatar_location(OsinfoInstallConfig *conf
*
* Please read documentation on #osinfo_install_config_set_target_disk() for
* explanation on the format of @disk string.
+ *
+ * Since: 0.2.2
*/
void osinfo_install_config_set_avatar_disk(OsinfoInstallConfig *config,
const gchar *disk)
@@ -686,6 +700,8 @@ void osinfo_install_config_set_avatar_disk(OsinfoInstallConfig *config,
*
* Returns: The value of #OSINFO_INSTALL_CONFIG_PROP_AVATAR_DISK parameter,
* or NULL.
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_install_config_get_avatar_disk(OsinfoInstallConfig *config)
{
@@ -727,6 +743,8 @@ void osinfo_install_config_set_pre_install_drivers_disk(OsinfoInstallConfig *con
*
* Returns: The disk on which pre-installation drivers are located, or NULL if
* its not set using #osinfo_install_config_set_pre_install_drivers_disk().
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_install_config_get_pre_install_drivers_disk(OsinfoInstallConfig *config)
{
@@ -747,6 +765,8 @@ const gchar *osinfo_install_config_get_pre_install_drivers_disk(OsinfoInstallCon
*
* Please read documentation on #osinfo_install_config_set_avatar_location() for
* explanation on the format of @location string.
+ *
+ * Since: 0.2.2
*/
void osinfo_install_config_set_pre_install_drivers_location(OsinfoInstallConfig *config,
const gchar *location)
@@ -762,6 +782,8 @@ void osinfo_install_config_set_pre_install_drivers_location(OsinfoInstallConfig
*
* Returns: The location on which pre-installation drivers are located, or NULL if
* its not set using #osinfo_install_config_set_pre_install_drivers_location().
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_install_config_get_pre_install_drivers_location(OsinfoInstallConfig *config)
{
@@ -784,6 +806,8 @@ const gchar *osinfo_install_config_get_pre_install_drivers_location(OsinfoInstal
* NOTE: Not every install script supports post-installation of drivers. Use
* #osinfo_install_script_get_can_post_install_drivers() to find out if an
* install script supports it.
+ *
+ * Since: 0.2.2
*/
void osinfo_install_config_set_post_install_drivers_disk(OsinfoInstallConfig *config,
const gchar *disk)
@@ -799,6 +823,8 @@ void osinfo_install_config_set_post_install_drivers_disk(OsinfoInstallConfig *co
*
* Returns: The disk on which post-installation drivers are located, or NULL if
* its not set using #osinfo_install_config_set_post_install_drivers_disk().
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_install_config_get_post_install_drivers_disk(OsinfoInstallConfig *config)
{
@@ -821,6 +847,8 @@ const gchar *osinfo_install_config_get_post_install_drivers_disk(OsinfoInstallCo
* NOTE: Not every install script supports post-installation of drivers. Use
* #osinfo_install_script_get_can_post_install_drivers() to find out if an
* install script supports it.
+ *
+ * Since: 0.2.2
*/
void osinfo_install_config_set_post_install_drivers_location(OsinfoInstallConfig *config,
const gchar *location)
@@ -836,6 +864,8 @@ void osinfo_install_config_set_post_install_drivers_location(OsinfoInstallConfig
*
* Returns: The disk on which post-installation drivers are located, or NULL if
* its not set using #osinfo_install_config_set_post_install_drivers_location().
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_install_config_get_post_install_drivers_location(OsinfoInstallConfig *config)
{
diff --git a/osinfo/osinfo_install_config_param.h b/osinfo/osinfo_install_config_param.h
index 047ab06..4c647d3 100644
--- a/osinfo/osinfo_install_config_param.h
+++ b/osinfo/osinfo_install_config_param.h
@@ -46,6 +46,7 @@ typedef struct _OsinfoInstallConfigParamClass OsinfoInstallConfigParamClass;
typedef struct _OsinfoInstallConfigParamPrivate OsinfoInstallConfigParamPrivate;
/**
* OsinfoInstallConfigParamPolicy:
+ * Since: 0.2.2
* @OSINFO_INSTALL_CONFIG_PARAM_POLICY_NONE: no policy defined
* @OSINFO_INSTALL_CONFIG_PARAM_POLICY_REQUIRED: config parameter is required
* @OSINFO_INSTALL_CONFIG_PARAM_POLICY_OPTIONAL: config parameter may be omitted
diff --git a/osinfo/osinfo_install_script.c b/osinfo/osinfo_install_script.c
index 6d68f1e..7e242c9 100644
--- a/osinfo/osinfo_install_script.c
+++ b/osinfo/osinfo_install_script.c
@@ -544,6 +544,8 @@ const gchar *osinfo_install_script_get_profile(OsinfoInstallScript *script)
* and 23.
*
* Returns: (transfer none): Product key format mask, or NULL.
+ *
+ * Since: 0.2.2
*/
const gchar *osinfo_install_script_get_product_key_format(OsinfoInstallScript *script)
{
@@ -642,6 +644,8 @@ osinfo_install_script_set_avatar_format(OsinfoInstallScript *script,
*
* Returns: (transfer none): The avatar format, or NULL if there is no restrictions on the
* format of avatar
+ *
+ * Since: 0.2.2
*/
OsinfoAvatarFormat *osinfo_install_script_get_avatar_format(OsinfoInstallScript *script)
{
@@ -1792,6 +1796,18 @@ gchar *osinfo_install_script_generate_command_line_for_media(OsinfoInstallScript
return output;
}
+/**
+ * osinfo_install_script_get_path_format:
+ * @script: the install script
+ *
+ * Returns the path format to be used for the files and disks which will
+ * be used during the installation.
+ *
+ * Returns: the path format to be used. OSINFO_PATH_FORMAT_UNIX is the
+ * default option.
+ *
+ * Since: 0.2.2
+ */
OsinfoPathFormat osinfo_install_script_get_path_format(OsinfoInstallScript *script)
{
return osinfo_entity_get_param_value_enum
@@ -1811,6 +1827,8 @@ OsinfoPathFormat osinfo_install_script_get_path_format(OsinfoInstallScript *scri
* available during actual installation.
*
* Returns: TRUE if install script supports pre-installable drivers, FALSE otherwise.
+ *
+ * Since: 0.2.2
*/
gboolean osinfo_install_script_get_can_pre_install_drivers(OsinfoInstallScript *script)
{
@@ -1819,6 +1837,18 @@ gboolean osinfo_install_script_get_can_pre_install_drivers(OsinfoInstallScript *
OSINFO_INSTALL_SCRIPT_PROP_CAN_PRE_INSTALL_DRIVERS);
}
+/**
+ * osinfo_install_script_get_can_post_install_drivers:
+ * @script: the install script
+ *
+ * Whether install script can install drivers at the very end of installation
+ * This can be used for installing devices which the OS in question does not
+ * have out of the box support.
+ *
+ * Returns: TRUE if install script supports post-installable drivers, FALSE otherwise.
+ *
+ * Since: 0.2.2
+ */
gboolean osinfo_install_script_get_can_post_install_drivers(OsinfoInstallScript *script)
{
return osinfo_entity_get_param_value_boolean
diff --git a/osinfo/osinfo_list.c b/osinfo/osinfo_list.c
index d0f2179..8f9a6a5 100644
--- a/osinfo/osinfo_list.c
+++ b/osinfo/osinfo_list.c
@@ -416,6 +416,8 @@ static OsinfoList *osinfo_list_new_same(OsinfoList *sourceOne,
* Construct a new list that is filled with elements from @source
*
* Returns: (transfer full): a copy of the list
+ *
+ * Since: 0.2.2
*/
OsinfoList *osinfo_list_new_copy(OsinfoList *source)
{
@@ -435,6 +437,8 @@ OsinfoList *osinfo_list_new_copy(OsinfoList *source)
* match @filter
*
* Returns: (transfer full): a filtered copy of the list
+ *
+ * Since: 0.2.2
*/
OsinfoList *osinfo_list_new_filtered(OsinfoList *source, OsinfoFilter *filter)
{
@@ -455,6 +459,8 @@ OsinfoList *osinfo_list_new_filtered(OsinfoList *source, OsinfoFilter *filter)
* that are present in both @sourceOne and @sourceTwo.
*
* Returns: (transfer full): an intersection of the two lists
+ *
+ * Since: 0.2.2
*/
OsinfoList *osinfo_list_new_intersection(OsinfoList *sourceOne,
OsinfoList *sourceTwo)
@@ -477,6 +483,8 @@ OsinfoList *osinfo_list_new_intersection(OsinfoList *sourceOne,
* the same type.
*
* Returns: (transfer full): a union of the two lists
+ *
+ * Since: 0.2.2
*/
OsinfoList *osinfo_list_new_union(OsinfoList *sourceOne,
OsinfoList *sourceTwo)
diff --git a/osinfo/osinfo_os.c b/osinfo/osinfo_os.c
index b2a71ce..61f2c69 100644
--- a/osinfo/osinfo_os.c
+++ b/osinfo/osinfo_os.c
@@ -1165,6 +1165,8 @@ void osinfo_os_add_install_script(OsinfoOs *os, OsinfoInstallScript *script)
* Gets list of all available device drivers for OS @os.
*
* Returns: (transfer none): A list of device drivers
+ *
+ * Since: 0.2.2
*/
OsinfoDeviceDriverList *osinfo_os_get_device_drivers(OsinfoOs *os)
{
@@ -1173,6 +1175,15 @@ OsinfoDeviceDriverList *osinfo_os_get_device_drivers(OsinfoOs *os)
return os->priv->device_drivers;
}
+/**
+ * osinfo_os_add_device_driver:
+ * @os: an operating system
+ * @driver: (transfer none): the device driver to add
+ *
+ * Adds @driver to the list of device drivers of operating system @os.
+ *
+ * Since: 0.2.2
+ */
void osinfo_os_add_device_driver(OsinfoOs *os, OsinfoDeviceDriver *driver)
{
g_return_if_fail(OSINFO_IS_OS(os));
--
2.21.0
More information about the Libosinfo
mailing list