From 8b8d3e28b26ae26364637f61525a73c0cfa45f62 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20Dre=C3=9Fler?= <verdre@v0yd.nl>
Date: Thu, 21 Nov 2019 17:09:16 +0700
Subject: [PATCH] st/icon: Update GtkDoc and annotations

Add missing documentation for some functions and make existing
documentation a bit more precise.

https://gitlab.gnome.org/GNOME/gnome-shell/merge_requests/888
---
 src/st/st-icon.c | 63 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 53 insertions(+), 10 deletions(-)

diff --git a/src/st/st-icon.c b/src/st/st-icon.c
index 4a92e9e5c..6cc7e4dba 100644
--- a/src/st/st-icon.c
+++ b/src/st/st-icon.c
@@ -495,6 +495,15 @@ st_icon_new (void)
   return g_object_new (ST_TYPE_ICON, NULL);
 }
 
+/**
+ * st_icon_get_icon_name:
+ * @icon: an #StIcon
+ *
+ * This is a convenience method to get the icon name of the #GThemedIcon that
+ * is currently set.
+ *
+ * Returns: (transfer none): The name of the icon or %NULL if no icon is set
+ */
 const gchar *
 st_icon_get_icon_name (StIcon *icon)
 {
@@ -510,6 +519,15 @@ st_icon_get_icon_name (StIcon *icon)
     return NULL;
 }
 
+/**
+ * st_icon_set_icon_name:
+ * @icon: an #StIcon
+ * @icon_name: (nullable): the name of the icon
+ *
+ * This is a convenience method to set the #GIcon to a #GThemedIcon created
+ * using the given icon name. If @icon_name is an empty string, %NULL or
+ * fails to load, the fallback icon will be shown.
+ */
 void
 st_icon_set_icon_name (StIcon      *icon,
                        const gchar *icon_name)
@@ -546,9 +564,11 @@ st_icon_set_icon_name (StIcon      *icon,
 
 /**
  * st_icon_get_gicon:
- * @icon: an icon
+ * @icon: an #StIcon
  *
- * Return value: (transfer none): the override GIcon, if set, or NULL
+ * Gets the current #GIcon in use.
+ *
+ * Returns: (transfer none): The current #GIcon, if set, otherwise %NULL
  */
 GIcon *
 st_icon_get_gicon (StIcon *icon)
@@ -560,8 +580,11 @@ st_icon_get_gicon (StIcon *icon)
 
 /**
  * st_icon_set_gicon:
- * @icon: an icon
- * @gicon: (nullable): a #GIcon to override :icon-name
+ * @icon: an #StIcon
+ * @gicon: (nullable): a #GIcon
+ *
+ * Sets a #GIcon to show for the icon. If @gicon is %NULL or fails to load,
+ * the fallback icon set using st_icon_set_fallback_icon() will be shown.
  */
 void
 st_icon_set_gicon (StIcon *icon, GIcon *gicon)
@@ -580,12 +603,12 @@ st_icon_set_gicon (StIcon *icon, GIcon *gicon)
 
 /**
  * st_icon_get_icon_size:
- * @icon: an icon
+ * @icon: an #StIcon
  *
- * Gets the size explicit size on the icon. This is not necesariily
- *  the size that the icon will actually be displayed at.
+ * Gets the explicit size set using st_icon_set_icon_size() for the icon.
+ * This is not necessarily the size that the icon will be displayed at.
  *
- * Return value: the size explicitly set, or -1 if no size has been set
+ * Returns: The explicitly set size, or -1 if no size has been set
  */
 gint
 st_icon_get_icon_size (StIcon *icon)
@@ -597,11 +620,12 @@ st_icon_get_icon_size (StIcon *icon)
 
 /**
  * st_icon_set_icon_size:
- * @icon: an icon
+ * @icon: an #StIcon
  * @size: if positive, the new size, otherwise the size will be
  *   derived from the current style
  *
- * Sets an explicit size for the icon.
+ * Sets an explicit size for the icon. Setting @size to -1 will use the size
+ * defined by the current style or the default icon size.
  */
 void
 st_icon_set_icon_size (StIcon *icon,
@@ -621,6 +645,15 @@ st_icon_set_icon_size (StIcon *icon,
     }
 }
 
+/**
+ * st_icon_get_fallback_icon_name:
+ * @icon: an #StIcon
+ *
+ * This is a convenience method to get the icon name of the fallback
+ * #GThemedIcon that is currently set.
+ *
+ * Returns: (transfer none): The name of the icon or %NULL if no icon is set
+ */
 const gchar *
 st_icon_get_fallback_icon_name (StIcon *icon)
 {
@@ -636,6 +669,16 @@ st_icon_get_fallback_icon_name (StIcon *icon)
     return NULL;
 }
 
+/**
+ * st_icon_set_fallback_icon_name:
+ * @icon: an #StIcon
+ * @fallback_icon_name: (nullable): the name of the fallback icon
+ *
+ * This is a convenience method to set the fallback #GIcon to a #GThemedIcon
+ * created using the given icon name. If @fallback_icon_name is an empty
+ * string, %NULL or fails to load, the icon is unset and no texture will
+ * be visible for the fallback icon.
+ */
 void
 st_icon_set_fallback_icon_name (StIcon      *icon,
                                 const gchar *fallback_icon_name)