[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