brl/gnome-shell
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

st/icon: Update GtkDoc and annotations

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

https://gitlab.gnome.org/GNOME/gnome-shell/merge_requests/888
This commit is contained in:
Jonas Dreßler 2019-11-21 17:09:16 +07:00 committed by Florian Müllner
parent 9b673dc98b
commit 8b8d3e28b2
1 changed files with 53 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
src/st/st-icon.c
View File

@ -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)