From 4f089f8489e292ced05a89ec7d761b9bc6533b84 Mon Sep 17 00:00:00 2001
From: Michal Ratajsky <michal.ratajsky@gmail.com>
Date: Thu, 28 Aug 2014 23:39:33 +0200
Subject: Documentation additions and fixes

---
 libmatemixer/matemixer-app-info.c | 78 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

(limited to 'libmatemixer/matemixer-app-info.c')

diff --git a/libmatemixer/matemixer-app-info.c b/libmatemixer/matemixer-app-info.c
index 65cba6c..0a32325 100644
--- a/libmatemixer/matemixer-app-info.c
+++ b/libmatemixer/matemixer-app-info.c
@@ -22,8 +22,20 @@
  * SECTION:matemixer-app-info
  * @short_description: Application information
  * @include: libmatemixer/matemixer.h
+ * @see_also: #MateMixerStreamControl
+ *
+ * The #MateMixerAppInfo structure describes application properties.
+ *
+ * See #MateMixerStreamControl and the mate_mixer_stream_control_get_app_info()
+ * function for more information.
  */
 
+/**
+ * MateMixerAppInfo:
+ *
+ * The #MateMixerAppInfo structure contains only private data and should only
+ * be accessed using the provided API.
+ */
 G_DEFINE_BOXED_TYPE (MateMixerAppInfo, mate_mixer_app_info,
                      _mate_mixer_app_info_copy,
                      _mate_mixer_app_info_free)
@@ -31,6 +43,10 @@ G_DEFINE_BOXED_TYPE (MateMixerAppInfo, mate_mixer_app_info,
 /**
  * mate_mixer_app_info_get_name:
  * @info: a #MateMixerAppInfo
+ *
+ * Gets the name of the application described by @info.
+ *
+ * Returns: name of the application or %NULL if it is unknown.
  */
 const gchar *
 mate_mixer_app_info_get_name (MateMixerAppInfo *info)
@@ -43,6 +59,11 @@ mate_mixer_app_info_get_name (MateMixerAppInfo *info)
 /**
  * mate_mixer_app_info_get_id:
  * @info: a #MateMixerAppInfo
+ *
+ * Gets the identifier of the application described by @info
+ * (e.g. org.example.app).
+ *
+ * Returns: identifier of the application or %NULL if it is unknown.
  */
 const gchar *
 mate_mixer_app_info_get_id (MateMixerAppInfo *info)
@@ -55,6 +76,10 @@ mate_mixer_app_info_get_id (MateMixerAppInfo *info)
 /**
  * mate_mixer_app_info_get_version:
  * @info: a #MateMixerAppInfo
+ *
+ * Gets the version of the application described by @info.
+ *
+ * Returns: version of the application or %NULL if it is unknown.
  */
 const gchar *
 mate_mixer_app_info_get_version (MateMixerAppInfo *info)
@@ -67,6 +92,10 @@ mate_mixer_app_info_get_version (MateMixerAppInfo *info)
 /**
  * mate_mixer_app_info_get_icon:
  * @info: a #MateMixerAppInfo
+ *
+ * Gets the XDG icon name of the application described by @info.
+ *
+ * Returns: icon name of the application or %NULL if it is unknown.
  */
 const gchar *
 mate_mixer_app_info_get_icon (MateMixerAppInfo *info)
@@ -76,12 +105,26 @@ mate_mixer_app_info_get_icon (MateMixerAppInfo *info)
     return info->icon;
 }
 
+/**
+ * _mate_mixer_app_info_new:
+ *
+ * Creates a new empty #MateMixerAppInfo structure.
+ *
+ * Returns: a new #MateMixerAppInfo.
+ */
 MateMixerAppInfo *
 _mate_mixer_app_info_new (void)
 {
     return g_slice_new0 (MateMixerAppInfo);
 }
 
+/**
+ * _mate_mixer_app_info_set_name:
+ * @info: a #MateMixerAppInfo
+ * @name: the application name to set
+ *
+ * Sets the name of the application described by @info.
+ */
 void
 _mate_mixer_app_info_set_name (MateMixerAppInfo *info, const gchar *name)
 {
@@ -92,6 +135,13 @@ _mate_mixer_app_info_set_name (MateMixerAppInfo *info, const gchar *name)
     info->name = g_strdup (name);
 }
 
+/**
+ * _mate_mixer_app_info_set_id:
+ * @info: a #MateMixerAppInfo
+ * @id: the application identifier to set
+ *
+ * Sets the identifier of the application described by @info.
+ */
 void
 _mate_mixer_app_info_set_id (MateMixerAppInfo *info, const gchar *id)
 {
@@ -102,6 +152,13 @@ _mate_mixer_app_info_set_id (MateMixerAppInfo *info, const gchar *id)
     info->id = g_strdup (id);
 }
 
+/**
+ * _mate_mixer_app_info_set_version:
+ * @info: a #MateMixerAppInfo
+ * @version: the application version to set
+ *
+ * Sets the version of the application described by @info.
+ */
 void
 _mate_mixer_app_info_set_version (MateMixerAppInfo *info, const gchar *version)
 {
@@ -112,6 +169,13 @@ _mate_mixer_app_info_set_version (MateMixerAppInfo *info, const gchar *version)
     info->version = g_strdup (version);
 }
 
+/**
+ * _mate_mixer_app_info_set_version:
+ * @info: a #MateMixerAppInfo
+ * @icon: the application icon name to set
+ *
+ * Sets the XDG icon name of the application described by @info.
+ */
 void
 _mate_mixer_app_info_set_icon (MateMixerAppInfo *info, const gchar *icon)
 {
@@ -122,6 +186,14 @@ _mate_mixer_app_info_set_icon (MateMixerAppInfo *info, const gchar *icon)
     info->icon = g_strdup (icon);
 }
 
+/**
+ * _mate_mixer_app_info_copy:
+ * @info: a #MateMixerAppInfo
+ *
+ * Creates a copy of the #MateMixerAppInfo.
+ *
+ * Returns: a copy of the given @info.
+ */
 MateMixerAppInfo *
 _mate_mixer_app_info_copy (MateMixerAppInfo *info)
 {
@@ -136,6 +208,12 @@ _mate_mixer_app_info_copy (MateMixerAppInfo *info)
     return info2;
 }
 
+/**
+ * _mate_mixer_app_info_free:
+ * @info: a #MateMixerAppInfo
+ *
+ * Frees the #MateMixerAppInfo.
+ */
 void
 _mate_mixer_app_info_free (MateMixerAppInfo *info)
 {
-- 
cgit v1.2.1