Documentation additions and fixes

9 files changed, 467 insertions, 89 deletions

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 4a6e205..fb3db04 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -61,8 +61,7 @@ IGNORE_HFILES=                                          \
         matemixer-stream-private.h                      \
         matemixer-switch-option-private.h               \
         matemixer-switch-private.h                      \
-        matemixer-private.h                             \
-        matemixer-types.h
+        matemixer-private.h
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
diff --git a/docs/reference/libmatemixer-sections.txt b/docs/reference/libmatemixer-sections.txt
index 46e8a8d..2b901e5 100644
--- a/docs/reference/libmatemixer-sections.txt
+++ b/docs/reference/libmatemixer-sections.txt
@@ -9,6 +9,7 @@ LIBMATEMIXER_CHECK_VERSION
 <SECTION>
 <FILE>matemixer-app-info</FILE>
 <TITLE>MateMixerAppInfo</TITLE>
+MateMixerAppInfo
 mate_mixer_app_info_get_name
 mate_mixer_app_info_get_id
 mate_mixer_app_info_get_version
@@ -16,6 +17,7 @@ mate_mixer_app_info_get_icon
 <SUBSECTION Standard>
 MATE_MIXER_APP_INFO
 MATE_MIXER_TYPE_APP_INFO
+<SUBSECTION Private>
 mate_mixer_app_info_get_type
 </SECTION>
 
@@ -50,7 +52,6 @@ mate_mixer_context_set_default_output_stream
 mate_mixer_context_get_backend_name
 mate_mixer_context_get_backend_type
 mate_mixer_context_get_backend_flags
-MateMixerContextPrivate
 <SUBSECTION Standard>
 MATE_MIXER_CONTEXT
 MATE_MIXER_CONTEXT_CLASS
@@ -59,6 +60,8 @@ MATE_MIXER_IS_CONTEXT
 MATE_MIXER_IS_CONTEXT_CLASS
 MATE_MIXER_TYPE_CONTEXT
 mate_mixer_context_get_type
+<SUBSECTION Private>
+MateMixerContextPrivate
 </SECTION>
 
 <SECTION>
@@ -73,7 +76,6 @@ mate_mixer_device_get_stream
 mate_mixer_device_get_switch
 mate_mixer_device_list_streams
 mate_mixer_device_list_switches
-MateMixerDevicePrivate
 <SUBSECTION Standard>
 MATE_MIXER_DEVICE
 MATE_MIXER_DEVICE_CLASS
@@ -82,6 +84,8 @@ MATE_MIXER_IS_DEVICE
 MATE_MIXER_IS_DEVICE_CLASS
 MATE_MIXER_TYPE_DEVICE
 mate_mixer_device_get_type
+<SUBSECTION Private>
+MateMixerDevicePrivate
 </SECTION>
 
 <SECTION>
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)
 {
diff --git a/libmatemixer/matemixer-backend-module.c b/libmatemixer/matemixer-backend-module.c
index bd71de0..7981b9f 100644
--- a/libmatemixer/matemixer-backend-module.c
+++ b/libmatemixer/matemixer-backend-module.c
@@ -213,7 +213,7 @@ mate_mixer_backend_module_get_info (MateMixerBackendModule *module)
  *
  * Gets file path to the backend module.
  *
- * Returns: string containing the path.
+ * Returns: the file path.
  */
 const gchar *
 mate_mixer_backend_module_get_path (MateMixerBackendModule *module)
diff --git a/libmatemixer/matemixer-context.c b/libmatemixer/matemixer-context.c
index bb28b18..88b4bf6 100644
--- a/libmatemixer/matemixer-context.c
+++ b/libmatemixer/matemixer-context.c
@@ -178,12 +178,12 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
     /**
      * MateMixerContext:app-icon:
      *
-     * An XDG icon name for the application.
+     * The XDG icon name of the application.
      */
     properties[PROP_APP_ICON] =
         g_param_spec_string ("app-icon",
                              "App icon",
-                             "Application icon name",
+                             "Application XDG icon name",
                              NULL,
                              G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 
@@ -192,8 +192,9 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
      *
      * Address of the sound server to connect to.
      *
-     * This feature is only supported in the PulseAudio backend. There is
-     * no need to specify an address in order to connect to the local daemon.
+     * This feature is only supported by the PulseAudio sound system.
+     * There is no need to specify an address in order to connect to the
+     * local PulseAudio daemon.
      */
     properties[PROP_SERVER_ADDRESS] =
         g_param_spec_string ("server-address",
@@ -202,6 +203,11 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
                              NULL,
                              G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 
+    /**
+     * MateMixerContext:state:
+     *
+     * The current state of the connection to a sound system.
+     */
     properties[PROP_STATE] =
         g_param_spec_enum ("state",
                            "State",
@@ -210,6 +216,14 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
                            MATE_MIXER_STATE_IDLE,
                            G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+    /**
+     * MateMixerContext:default-input-stream:
+     *
+     * The stream sound input most likely comes from by default.
+     *
+     * See mate_mixer_context_set_default_input_stream() for more information
+     * about changing the default input stream.
+     */
     properties[PROP_DEFAULT_INPUT_STREAM] =
         g_param_spec_object ("default-input-stream",
                              "Default input stream",
@@ -217,6 +231,14 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
                              MATE_MIXER_TYPE_STREAM,
                              G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
 
+    /**
+     * MateMixerContext:default-output-stream:
+     *
+     * The stream sound output is most likely directed to by default.
+     *
+     * See mate_mixer_context_set_default_output_stream() for more information
+     * about changing the default output stream.
+     */
     properties[PROP_DEFAULT_OUTPUT_STREAM] =
         g_param_spec_object ("default-output-stream",
                              "Default output stream",
@@ -232,6 +254,11 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
      * @name: name of the added device
      *
      * The signal is emitted each time a device is added to the system.
+     *
+     * Use mate_mixer_context_get_device() to get the #MateMixerDevice.
+     *
+     * Note that at the time this signal is emitted, the streams and switches
+     * of the device may not yet be known.
      */
     signals[DEVICE_ADDED] =
         g_signal_new ("device-added",
@@ -251,6 +278,11 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
      * @name: name of the removed device
      *
      * The signal is emitted each time a device is removed from the system.
+     *
+     * When this signal is emitted, the device is no longer known to the library,
+     * it will not be included in the device list provided by the
+     * mate_mixer_context_list_devices() function and it is not possible to get
+     * the device with mate_mixer_context_get_device().
      */
     signals[DEVICE_REMOVED] =
         g_signal_new ("device-removed",
@@ -269,7 +301,14 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
      * @context: a #MateMixerContext
      * @name: name of the added stream
      *
-     * The signal is emitted each time a stream is created.
+     * The signal is emitted each time a stream is added.
+     *
+     * This signal is emitted for streams which belong to devices as well as
+     * streams which do not. If you are only interested in streams of a
+     * specific device, the signal is also available in #MateMixerDevice.
+     *
+     * Note that at the time this signal is emitted, the controls and switches
+     * of the stream may not yet be known.
      */
     signals[STREAM_ADDED] =
         g_signal_new ("stream-added",
@@ -289,6 +328,15 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
      * @name: name of the removed stream
      *
      * The signal is emitted each time a stream is removed.
+     *
+     * When this signal is emitted, the stream is no longer known to the library,
+     * it will not be included in the stream list provided by the
+     * mate_mixer_context_list_streams() function and it is not possible to get
+     * the stream with mate_mixer_context_get_stream().
+     *
+     * This signal is emitted for streams which belong to devices as well as
+     * streams which do not. If you are only interested in streams of a
+     * specific device, the signal is also available in #MateMixerDevice.
      */
     signals[STREAM_REMOVED] =
         g_signal_new ("stream-removed",
@@ -307,7 +355,9 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
      * @context: a #MateMixerContext
      * @name: name of the added stored control
      *
-     * The signal is emitted each time a stored control is created.
+     * The signal is emitted each time a stored control is added.
+     *
+     * Use mate_mixer_context_get_stored_control() to get the #MateMixerStoredControl.
      */
     signals[STORED_CONTROL_ADDED] =
         g_signal_new ("stored-control-added",
@@ -324,9 +374,14 @@ mate_mixer_context_class_init (MateMixerContextClass *klass)
     /**
      * MateMixerContext::stored-control-removed:
      * @context: a #MateMixerContext
-     * @name: name of the removed control
+     * @name: name of the removed stored control
      *
-     * The signal is emitted each time a control is removed.
+     * The signal is emitted each time a stored control is removed.
+     *
+     * When this signal is emitted, the stored control is no longer known to the
+     * library, it will not be included in the stream list provided by the
+     * mate_mixer_context_list_stored_controls() function and it is not possible to
+     * get the stored control with mate_mixer_context_get_stored_control().
      */
     signals[STORED_CONTROL_REMOVED] =
         g_signal_new ("stored-control-removed",
@@ -466,7 +521,7 @@ mate_mixer_context_finalize (GObject *object)
  * Creates a new #MateMixerContext instance.
  *
  * Returns: a new #MateMixerContext instance or %NULL if the library has not
- * been initialized using mate_mixer_init().
+ * been initialized with mate_mixer_init().
  */
 MateMixerContext *
 mate_mixer_context_new (void)
@@ -487,12 +542,11 @@ mate_mixer_context_new (void)
  * Makes the #MateMixerContext use the given #MateMixerBackendType.
  *
  * By default the backend type is determined automatically. This function can
- * be used before mate_mixer_context_open() to alter this behavior and make the
- * @context use the given backend.
+ * be used to alter this behavior and make the @context use the selected sound
+ * system.
  *
- * This function will fail if support for the backend is not installed in
- * the system or if the current state is either %MATE_MIXER_STATE_CONNECTING or
- * %MATE_MIXER_STATE_READY.
+ * This function must be used before opening a connection to a sound system with
+ * mate_mixer_context_open(), otherwise it will fail.
  *
  * Returns: %TRUE on success or %FALSE on failure.
  */
@@ -530,12 +584,11 @@ mate_mixer_context_set_backend_type (MateMixerContext     *context,
  * @context: a #MateMixerContext
  * @app_name: the name of your application, or %NULL to unset
  *
- * Sets the name of the application. This feature is only supported in the
- * PulseAudio backend.
+ * Sets the name of your application. This information may be used when
+ * registering with the sound system.
  *
- * This function will fail if the current state is either
- * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should
- * use it before opening a connection to the sound system.
+ * This function must be used before opening a connection to a sound system with
+ * mate_mixer_context_open(), otherwise it will fail.
  *
  * Returns: %TRUE on success or %FALSE on failure.
  */
@@ -561,12 +614,11 @@ mate_mixer_context_set_app_name (MateMixerContext *context, const gchar *app_nam
  * @context: a #MateMixerContext
  * @app_id: the identifier of your application, or %NULL to unset
  *
- * Sets the identifier of the application (e.g. org.example.app). This feature
- * is only supported in the PulseAudio backend.
+ * Sets the identifier of your application (e.g. org.example.app). This
+ * information may be used when registering with the sound system.
  *
- * This function will fail if the current state is either
- * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should
- * use it before opening a connection to the sound system.
+ * This function must be used before opening a connection to a sound system with
+ * mate_mixer_context_open(), otherwise it will fail.
  *
  * Returns: %TRUE on success or %FALSE on failure.
  */
@@ -592,12 +644,11 @@ mate_mixer_context_set_app_id (MateMixerContext *context, const gchar *app_id)
  * @context: a #MateMixerContext
  * @app_version: the version of your application, or %NULL to unset
  *
- * Sets the version of the application. This feature is only supported in the
- * PulseAudio backend.
+ * Sets the version of your application. This information may be used when
+ * registering with the sound system.
  *
- * This function will fail if the current state is either
- * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should
- * use it before opening a connection to the sound system.
+ * This function must be used before opening a connection to a sound system with
+ * mate_mixer_context_open(), otherwise it will fail.
  *
  * Returns: %TRUE on success or %FALSE on failure.
  */
@@ -623,12 +674,11 @@ mate_mixer_context_set_app_version (MateMixerContext *context, const gchar *app_
  * @context: a #MateMixerContext
  * @app_icon: the XDG icon name of your application, or %NULL to unset
  *
- * Sets the XDG icon name of the application. This feature is only supported in
- * the PulseAudio backend.
+ * Sets the XDG icon name of your application. This information may be used when
+ * registering with the sound system.
  *
- * This function will fail if the current state is either
- * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should
- * use it before opening a connection to the sound system.
+ * This function must be used before opening a connection to a sound system with
+ * mate_mixer_context_open(), otherwise it will fail.
  *
  * Returns: %TRUE on success or %FALSE on failure.
  */
@@ -658,9 +708,8 @@ mate_mixer_context_set_app_icon (MateMixerContext *context, const gchar *app_ico
  * PulseAudio backend. If the address is not set, the default PulseAudio sound
  * server will be used, which is normally the local daemon.
  *
- * This function will fail if the current state is either
- * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should
- * use it before opening a connection to the sound system.
+ * This function must be used before opening a connection to a sound system with
+ * mate_mixer_context_open(), otherwise it will fail.
  *
  * Returns: %TRUE on success or %FALSE on failure.
  */
@@ -687,24 +736,30 @@ mate_mixer_context_set_server_address (MateMixerContext *context, const gchar *a
  * mate_mixer_context_open:
  * @context: a #MateMixerContext
  *
- * Opens connection to a sound system. Unless the backend type was given
- * beforehand, the library will find a working sound system automatically.
- * If the automatic discovery fails to find a working sound system, it will
- * use the "Null" backend, which provides no functionality.
+ * Opens connection to a sound system. Unless the sound system backend type
+ * was chosen manually with mate_mixer_context_set_backend_type(), the library
+ * will find a working sound system automatically.
  *
  * This function can complete the operation either synchronously or
- * asynchronously.
+ * asynchronously and it may go through a series of connection
+ * #MateMixerContext:state transitions.
+ *
+ * If this function returns %TRUE, the connection has either been established, or
+ * it hasn't been established yet and the result will be determined asynchronously.
+ * You can differentiate between these two possibilities by checking the connection
+ * #MateMixerContext:state.
  *
- * In case this function returns %TRUE, you should check the current state of
- * the connection using mate_mixer_context_get_state(). If the current state
- * is %MATE_MIXER_STATE_READY, the connection has been established successfully.
- * Otherwise the state will be set to %MATE_MIXER_STATE_CONNECTING and the
- * result of the operation will be determined asynchronously. You should wait
- * for the state transition by connecting to the notification signal of the
- * #MateMixerContext:state property.
+ * The %MATE_MIXER_STATE_READY state indicates, that the connection has been
+ * established successfully.
  *
- * In case this function returns %FALSE, it is not possible to use the selected
- * backend and the state will be set to %MATE_MIXER_STATE_FAILED.
+ * The %MATE_MIXER_STATE_CONNECTING state is reached when the connection has not been
+ * established yet and you should wait for the state to change to either
+ * %MATE_MIXER_STATE_READY or %MATE_MIXER_STATE_FAILED. It is required to have a main
+ * loop running to allow an asynchronous connection to proceed. The library will use
+ * the thread's default main context for this purpose.
+ *
+ * If this function returns %FALSE, it was not possible to connect to a sound system
+ * and the #MateMixerContext:state will be set to %MATE_MIXER_STATE_FAILED.
  *
  * Returns: %TRUE on success or if the result will be determined asynchronously,
  * or %FALSE on failure.
@@ -807,8 +862,8 @@ mate_mixer_context_open (MateMixerContext *context)
  * mate_mixer_context_close:
  * @context: a #MateMixerContext
  *
- * Closes connection to the currently used sound system. The state will be
- * set to %MATE_MIXER_STATE_IDLE.
+ * Closes an open connection to the sound system. The #MateMixerContext:state
+ * will be set to %MATE_MIXER_STATE_IDLE.
  */
 void
 mate_mixer_context_close (MateMixerContext *context)
@@ -823,9 +878,9 @@ mate_mixer_context_close (MateMixerContext *context)
  * mate_mixer_context_get_state:
  * @context: a #MateMixerContext
  *
- * Gets the current backend connection state of the #MateMixerContext.
+ * Gets the state of the @context's connection to a sound system.
  *
- * Returns: The current connection state.
+ * Returns: the connection state.
  */
 MateMixerState
 mate_mixer_context_get_state (MateMixerContext *context)
@@ -884,7 +939,7 @@ mate_mixer_context_get_stream (MateMixerContext *context, const gchar *name)
  *
  * Gets the stored control with the given name.
  *
- * Returns: a #MateMixerStoredControl or %NULL if there is no such control.
+ * Returns: a #MateMixerStoredControl or %NULL if there is no such stored control.
  */
 MateMixerStoredControl *
 mate_mixer_context_get_stored_control (MateMixerContext *context, const gchar *name)
@@ -902,11 +957,10 @@ mate_mixer_context_get_stored_control (MateMixerContext *context, const gchar *n
  * mate_mixer_context_list_devices:
  * @context: a #MateMixerContext
  *
- * Gets a list of devices. Each list item is a #MateMixerDevice representing a
- * hardware or software sound device in the system.
+ * Gets a list of devices. Each item in the list is a #MateMixerDevice representing
+ * a sound device in the system.
  *
- * The returned #GList is owned by the #MateMixerContext and may be invalidated
- * at any time.
+ * The returned #GList is owned by the library and may be invalidated at any time.
  *
  * Returns: a #GList of all devices in the system or %NULL if there are none or
  * you are not connected to a sound system.
@@ -926,11 +980,14 @@ mate_mixer_context_list_devices (MateMixerContext *context)
  * mate_mixer_context_list_streams:
  * @context: a #MateMixerContext
  *
- * Gets a list of streams. Each list item is a #MateMixerStream representing an
- * input or output of a sound device.
+ * Gets a list of streams. Each item in the list is a #MateMixerStream representing
+ * an input or output stream.
+ *
+ * Note that the list will contain streams which belong to devices as well
+ * as streams which do not. If you are only interested in streams of a specific
+ * device, use mate_mixer_device_list_streams().
  *
- * The returned #GList is owned by the #MateMixerContext and may be invalidated
- * at any time.
+ * The returned #GList is owned by the library and may be invalidated at any time.
  *
  * Returns: a #GList of all streams in the system or %NULL if there are none or
  * you are not connected to a sound system.
@@ -950,6 +1007,12 @@ mate_mixer_context_list_streams (MateMixerContext *context)
  * mate_mixer_context_list_stored_controls:
  * @context: a #MateMixerContext
  *
+ * Gets a list of stored controls. Each item in the list is a #MateMixerStoredControl.
+ *
+ * The returned #GList is owned by the library and may be invalidated at any time.
+ *
+ * Returns: a #GList of stored controls or %NULL if there are none or you are not
+ * connected to a sound system.
  */
 const GList *
 mate_mixer_context_list_stored_controls (MateMixerContext *context)
@@ -966,11 +1029,10 @@ mate_mixer_context_list_stored_controls (MateMixerContext *context)
  * mate_mixer_context_get_default_input_stream:
  * @context: a #MateMixerContext
  *
- * Gets the default input stream. The returned stream is where sound input is
- * directed to by default.
+ * Gets the default input stream. The returned stream is where sound input
+ * most likely comes from by default.
  *
- * Returns: a #MateMixerStream or %NULL if there are no input streams in
- * the system.
+ * Returns: a #MateMixerStream or %NULL if there is no default input stream.
  */
 MateMixerStream *
 mate_mixer_context_get_default_input_stream (MateMixerContext *context)
@@ -988,8 +1050,10 @@ mate_mixer_context_get_default_input_stream (MateMixerContext *context)
  * @context: a #MateMixerContext
  * @stream: a #MateMixerStream to set as the default input stream
  *
- * Changes the default input stream in the system. The @stream must be an
- * input non-client stream.
+ * Changes the default input stream. The given @stream must be an input stream.
+ *
+ * Changing the default input stream may not be supported by the sound system.
+ * Use mate_mixer_context_get_backend_flags() to find out.
  *
  * Returns: %TRUE on success or %FALSE on failure.
  */
@@ -1016,7 +1080,7 @@ mate_mixer_context_set_default_input_stream (MateMixerContext *context,
  * @context: a #MateMixerContext
  *
  * Gets the default output stream. The returned stream is where sound output is
- * directed to by default.
+ * most likely directed to by default.
  *
  * Returns: a #MateMixerStream or %NULL if there are no output streams in
  * the system.
@@ -1037,8 +1101,10 @@ mate_mixer_context_get_default_output_stream (MateMixerContext *context)
  * @context: a #MateMixerContext
  * @stream: a #MateMixerStream to set as the default output stream
  *
- * Changes the default output stream in the system. The @stream must be an
- * output non-client stream.
+ * Changes the default output stream. The given @stream must be an output stream.
+ *
+ * Changing the default output stream may not be supported by the sound system.
+ * Use mate_mixer_context_get_backend_flags() to find out.
  *
  * Returns: %TRUE on success or %FALSE on failure.
  */
@@ -1064,8 +1130,8 @@ mate_mixer_context_set_default_output_stream (MateMixerContext *context,
  * mate_mixer_context_get_backend_name:
  * @context: a #MateMixerContext
  *
- * Gets the name of the currently used backend. This function will not
- * work until connected to a sound system.
+ * Gets the name of the currently used sound system backend. This function will
+ * not work until connected to a sound system.
  *
  * Returns: the name or %NULL on error.
  */
@@ -1084,8 +1150,8 @@ mate_mixer_context_get_backend_name (MateMixerContext *context)
  * mate_mixer_context_get_backend_type:
  * @context: a #MateMixerContext
  *
- * Gets the type of the currently used backend. This function will not
- * work until connected to a sound system.
+ * Gets the type of the currently used sound system backend. This function will
+ * not work until connected to a sound system.
  *
  * Returns: the backend type or %MATE_MIXER_BACKEND_UNKNOWN on error.
  */
@@ -1103,6 +1169,11 @@ mate_mixer_context_get_backend_type (MateMixerContext *context)
 /**
  * mate_mixer_context_get_backend_flags:
  * @context: a #MateMixerContext
+ *
+ * Gets the capability flags of the currently used sound system backend. This
+ * function will not work until connected to a sound system.
+ *
+ * Returns: the capability flags.
  */
 MateMixerBackendFlags
 mate_mixer_context_get_backend_flags (MateMixerContext *context)
diff --git a/libmatemixer/matemixer-device.c b/libmatemixer/matemixer-device.c
index 8144388..3944af5 100644
--- a/libmatemixer/matemixer-device.c
+++ b/libmatemixer/matemixer-device.c
@@ -90,6 +90,13 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass)
     object_class->get_property = mate_mixer_device_get_property;
     object_class->set_property = mate_mixer_device_set_property;
 
+    /**
+     * MateMixerDevice:name:
+     *
+     * The name of the device. The name serves as a unique identifier and
+     * in most cases it is not in a user-readable form.
+     *
+     */
     properties[PROP_NAME] =
         g_param_spec_string ("name",
                              "Name",
@@ -99,6 +106,12 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass)
                              G_PARAM_CONSTRUCT_ONLY |
                              G_PARAM_STATIC_STRINGS);
 
+    /**
+     * MateMixerDevice:label:
+     *
+     * The label of the device. This is a potentially translated string
+     * that should be presented to users in the user interface.
+     */
     properties[PROP_LABEL] =
         g_param_spec_string ("label",
                              "Label",
@@ -108,10 +121,15 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass)
                              G_PARAM_CONSTRUCT_ONLY |
                              G_PARAM_STATIC_STRINGS);
 
+    /**
+     * MateMixerDevice:icon:
+     *
+     * The XDG icon name of the device.
+     */
     properties[PROP_ICON] =
         g_param_spec_string ("icon",
                              "Icon",
-                             "Name of the sound device icon",
+                             "XDG icon name of the device",
                              NULL,
                              G_PARAM_READWRITE |
                              G_PARAM_CONSTRUCT_ONLY |
@@ -119,6 +137,16 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass)
 
     g_object_class_install_properties (object_class, N_PROPERTIES, properties);
 
+    /**
+     * MateMixerDevice::stream-added:
+     * @device: a #MateMixerDevice
+     * @name: name of the added stream
+     *
+     * The signal is emitted each time a device stream is added.
+     *
+     * Note that at the time this signal is emitted, the controls and switches
+     * of the stream may not yet be known.
+     */
     signals[STREAM_ADDED] =
         g_signal_new ("stream-added",
                       G_TYPE_FROM_CLASS (object_class),
@@ -131,6 +159,18 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass)
                       1,
                       G_TYPE_STRING);
 
+    /**
+     * MateMixerDevice::stream-removed:
+     * @device: a #MateMixerDevice
+     * @name: name of the removed stream
+     *
+     * The signal is emitted each time a device stream is removed.
+     *
+     * When this signal is emitted, the stream is no longer known to the library,
+     * it will not be included in the stream list provided by the
+     * mate_mixer_device_list_streams() function and it is not possible to get
+     * the stream with mate_mixer_device_get_stream().
+     */
     signals[STREAM_REMOVED] =
         g_signal_new ("stream-removed",
                       G_TYPE_FROM_CLASS (object_class),
@@ -143,6 +183,13 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass)
                       1,
                       G_TYPE_STRING);
 
+    /**
+     * MateMixerDevice::switch-added:
+     * @device: a #MateMixerDevice
+     * @name: name of the added switch
+     *
+     * The signal is emitted each time a device switch is added.
+     */
     signals[SWITCH_ADDED] =
         g_signal_new ("switch-added",
                       G_TYPE_FROM_CLASS (object_class),
@@ -155,6 +202,18 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass)
                       1,
                       G_TYPE_STRING);
 
+    /**
+     * MateMixerDevice::switch-removed:
+     * @device: a #MateMixerDevice
+     * @name: name of the removed switch
+     *
+     * The signal is emitted each time a device switch is removed.
+     *
+     * When this signal is emitted, the switch is no longer known to the library,
+     * it will not be included in the switch list provided by the
+     * mate_mixer_device_list_switches() function and it is not possible to get
+     * the switch with mate_mixer_device_get_switch().
+     */
     signals[SWITCH_REMOVED] =
         g_signal_new ("switch-removed",
                       G_TYPE_FROM_CLASS (object_class),
@@ -251,6 +310,15 @@ mate_mixer_device_finalize (GObject *object)
 /**
  * mate_mixer_device_get_name:
  * @device: a #MateMixerDevice
+ *
+ * Gets the name of the device. The name serves as a unique identifier and
+ * in most cases it is not in a user-readable form.
+ *
+ * The returned name is guaranteed to be unique across all the known devices
+ * and may be used to get the #MateMixerDevice using
+ * mate_mixer_context_get_device().
+ *
+ * Returns: the name of the device.
  */
 const gchar *
 mate_mixer_device_get_name (MateMixerDevice *device)
@@ -263,6 +331,11 @@ mate_mixer_device_get_name (MateMixerDevice *device)
 /**
  * mate_mixer_device_get_label:
  * @device: a #MateMixerDevice
+ *
+ * Gets the label of the device. This is a potentially translated string
+ * that should be presented to users in the user interface.
+ *
+ * Returns: the label of the device.
  */
 const gchar *
 mate_mixer_device_get_label (MateMixerDevice *device)
@@ -275,6 +348,10 @@ mate_mixer_device_get_label (MateMixerDevice *device)
 /**
  * mate_mixer_device_get_icon:
  * @device: a #MateMixerDevice
+ *
+ * Gets the XDG icon name of the device.
+ *
+ * Returns: the icon name.
  */
 const gchar *
 mate_mixer_device_get_icon (MateMixerDevice *device)
@@ -288,6 +365,10 @@ mate_mixer_device_get_icon (MateMixerDevice *device)
  * mate_mixer_device_get_stream:
  * @device: a #MateMixerDevice
  * @name: a stream name
+ *
+ * Gets the device stream with the given name.
+ *
+ * Returns: a #MateMixerStream or %NULL if there is no such stream.
  */
 MateMixerStream *
 mate_mixer_device_get_stream (MateMixerDevice *device, const gchar *name)
@@ -299,6 +380,17 @@ mate_mixer_device_get_stream (MateMixerDevice *device, const gchar *name)
  * mate_mixer_device_get_switch:
  * @device: a #MateMixerDevice
  * @name: a switch name
+ *
+ * Gets the device switch with the given name.
+ *
+ * Note that this function will only return a switch that belongs to the device
+ * and not to a stream of the device. See mate_mixer_device_list_switches() for
+ * information about the difference between device and stream switches.
+ *
+ * To get a stream switch, rather than a device switch, use
+ * mate_mixer_stream_get_switch().
+ *
+ * Returns: a #MateMixerSwitch or %NULL if there is no such device switch.
  */
 MateMixerSwitch *
 mate_mixer_device_get_switch (MateMixerDevice *device, const gchar *name)
@@ -309,6 +401,14 @@ mate_mixer_device_get_switch (MateMixerDevice *device, const gchar *name)
 /**
  * mate_mixer_device_list_streams:
  * @device: a #MateMixerDevice
+ *
+ * Gets the list of streams that belong to the device.
+ *
+ * The returned #GList is owned by the #MateMixerDevice and may be invalidated
+ * at any time.
+ *
+ * Returns: a #GList of the device streams or %NULL if the device does not have
+ * any streams.
  */
 const GList *
 mate_mixer_device_list_streams (MateMixerDevice *device)
@@ -328,6 +428,21 @@ mate_mixer_device_list_streams (MateMixerDevice *device)
 /**
  * mate_mixer_device_list_switches:
  * @device: a #MateMixerDevice
+ *
+ * Gets the list of switches the belong to the device.
+ *
+ * Note that a switch may belong either to a device, or to a stream. Unlike
+ * stream switches, device switches returned by this function are not classified
+ * as input or output (as streams are), but they operate on the whole device.
+ *
+ * Use mate_mixer_stream_list_switches() to get a list of switches that belong
+ * to a stream.
+ *
+ * The returned #GList is owned by the #MateMixerDevice and may be invalidated
+ * at any time.
+ *
+ * Returns: a #GList of the device switches or %NULL if the device does not have
+ * any switches.
  */
 const GList *
 mate_mixer_device_list_switches (MateMixerDevice *device)
diff --git a/libmatemixer/matemixer-enums.h b/libmatemixer/matemixer-enums.h
index 97d2f26..3f2fa44 100644
--- a/libmatemixer/matemixer-enums.h
+++ b/libmatemixer/matemixer-enums.h
@@ -26,10 +26,17 @@
 /**
  * MateMixerState:
  * @MATE_MIXER_STATE_IDLE:
+ *     Not connected.
  * @MATE_MIXER_STATE_CONNECTING:
+ *     Connection is in progress.
  * @MATE_MIXER_STATE_READY:
+ *     Connected successfully.
  * @MATE_MIXER_STATE_FAILED:
+ *     Connection has failed.
  * @MATE_MIXER_STATE_UNKNOWN:
+ *     Unknown state. This state is used as an error indicator.
+ *
+ * State of a connection to a sound system.
  */
 typedef enum {
     MATE_MIXER_STATE_IDLE,
@@ -45,8 +52,8 @@ typedef enum {
  *     Unknown or undefined backend type.
  * @MATE_MIXER_BACKEND_PULSEAUDIO:
  *     PulseAudio sound system backend. It has the highest priority and
- *     will be the first one to try unless you select a specific backend
- *     to connect to.
+ *     will be the first one to try when you call mate_mixer_context_open(),
+ *     unless you select a specific sound system to connect to.
  * @MATE_MIXER_BACKEND_ALSA:
  *     The Advanced Linux Sound Architecture sound system.
  * @MATE_MIXER_BACKEND_OSS:
@@ -54,8 +61,10 @@ typedef enum {
  * @MATE_MIXER_BACKEND_NULL:
  *     Fallback backend which never fails to initialize, but provides no
  *     functionality. This backend has the lowest priority and will be used
- *     if you do not select a specific backend to connect to and all the
- *     "real" backends fail to initialize.
+ *     if you do not select a specific backend and it isn't possible to use
+ *     any of the other backends.
+ *
+ * Constants identifying a sound system backend.
  */
 typedef enum {
     MATE_MIXER_BACKEND_UNKNOWN,
@@ -77,6 +86,8 @@ typedef enum {
  * @MATE_MIXER_BACKEND_CAN_SET_DEFAULT_OUTPUT_STREAM:
  *     The backend is able to change the current default output stream using
  *     the mate_mixer_context_set_default_output_stream() function.
+ *
+ * Flags describing capabilities of a sound system.
  */
 typedef enum { /*< flags >*/
     MATE_MIXER_BACKEND_NO_FLAGS                         = 0,
@@ -93,6 +104,8 @@ typedef enum { /*< flags >*/
  *     Input direction (recording).
  * @MATE_MIXER_DIRECTION_OUTPUT:
  *     Output direction (playback).
+ *
+ * Sound stream direction.
  */
 typedef enum {
     MATE_MIXER_DIRECTION_UNKNOWN,
@@ -107,17 +120,30 @@ typedef enum {
  * @MATE_MIXER_STREAM_CONTROL_MUTE_READABLE:
  *     The stream control includes a mute toggle and allows reading the mute state.
  * @MATE_MIXER_STREAM_CONTROL_MUTE_WRITABLE:
+ *     The stream control includes a mute toggle and allows changing the mute state.
  * @MATE_MIXER_STREAM_CONTROL_VOLUME_READABLE:
+ *     The stream control includes a volume control and allows reading the volume.
  * @MATE_MIXER_STREAM_CONTROL_VOLUME_WRITABLE:
+ *     The stream control includes a volume control and allows changing the volume.
  * @MATE_MIXER_STREAM_CONTROL_CAN_BALANCE:
+ *     The stream control includes the necessary channel positions to allow left/right
+ *     volume balancing.
  * @MATE_MIXER_STREAM_CONTROL_CAN_FADE:
+ *     The stream control includes the necessary channel positions to allow front/back
+ *     volume fading.
  * @MATE_MIXER_STREAM_CONTROL_MOVABLE:
  *     It is possible to move the stream control to a different stream using the
  *     mate_mixer_stream_control_set_stream() function. See the function description
  *     for details.
  * @MATE_MIXER_STREAM_CONTROL_HAS_DECIBEL:
+ *     The stream controls supports decibel values and it is possible to successfully
+ *     use the functions which operate on decibel values.
  * @MATE_MIXER_STREAM_CONTROL_HAS_MONITOR:
+ *     The stream control supports peak level monitoring.
  * @MATE_MIXER_STREAM_CONTROL_STORED:
+ *     The stream control is a #MateMixerStoredControl.
+ *
+ * Flags describing capabilities and properties of a stream control.
  */
 typedef enum {
     MATE_MIXER_STREAM_CONTROL_NO_FLAGS        = 0,
@@ -133,6 +159,35 @@ typedef enum {
     MATE_MIXER_STREAM_CONTROL_STORED          = 1 << 9
 } MateMixerStreamControlFlags;
 
+/**
+ * MateMixerStreamControlRole:
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_UNKNOWN:
+ *     Unknown role.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_MASTER:
+ *     Master volume control.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_APPLICATION:
+ *     Application volume control.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_PCM:
+ *     PCM volume control.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_SPEAKER:
+ *     Speaker volume control.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_MICROPHONE:
+ *     Microphone volume control.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_PORT:
+ *     Volume control for a connector of a sound device.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_BOOST:
+ *     Boost control (for example a microphone boost or bass boost).
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_BASS:
+ *     Bass control.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_TREBLE:
+ *     Treble control.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_CD:
+ *     CD input volume control.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_VIDEO:
+ *     Video volume control.
+ * @MATE_MIXER_STREAM_CONTROL_ROLE_MUSIC:
+ *     Music volume control.
+ */
 typedef enum {
     MATE_MIXER_STREAM_CONTROL_ROLE_UNKNOWN,
     MATE_MIXER_STREAM_CONTROL_ROLE_MASTER,
@@ -149,6 +204,32 @@ typedef enum {
     MATE_MIXER_STREAM_CONTROL_ROLE_MUSIC
 } MateMixerStreamControlRole;
 
+/**
+ * MateMixerStreamControlMediaRole:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_UNKNOWN:
+ *     Unknown media role.
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_VIDEO:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_MUSIC:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_GAME:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_EVENT:
+ *     Event sounds.
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_PHONE:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_ANIMATION:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_PRODUCTION:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_A11Y:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_TEST:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_ABSTRACT:
+ * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_FILTER:
+ *
+ * Constants describing a media role of a control. These constants are mapped
+ * to PulseAudio media role property and therefore only available when using the
+ * PulseAudio sound system.
+ *
+ * Media roles are commonly set by applications to indicate what kind of sound
+ * input/output they provide and may be the defining property of stored controls
+ * (for example an event role stored control can be used to provide a volume
+ * slider for event sounds).
+ */
 typedef enum {
     MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_UNKNOWN,
     MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_VIDEO,
@@ -164,12 +245,30 @@ typedef enum {
     MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_FILTER
 } MateMixerStreamControlMediaRole;
 
+/**
+ * MateMixerSwitchFlags:
+ * @MATE_MIXER_SWITCH_NO_FLAGS:
+ *     No flags.
+ * @MATE_MIXER_SWITCH_TOGGLE:
+ *     The switch is a #MateMixerToggle.
+ */
 typedef enum { /*< flags >*/
     MATE_MIXER_SWITCH_NO_FLAGS                = 0,
     MATE_MIXER_SWITCH_TOGGLE                  = 1 << 0,
     MATE_MIXER_SWITCH_ALLOWS_NO_ACTIVE_OPTION = 1 << 1
 } MateMixerSwitchFlags;
 
+/**
+ * MateMixerSwitchRole:
+ * @MATE_MIXER_SWITCH_ROLE_UNKNOWN:
+ *     Unknown switch role.
+ * @MATE_MIXER_SWITCH_ROLE_DEVICE_PROFILE:
+ *     The switch changes the active sound device profile.
+ * @MATE_MIXER_SWITCH_ROLE_PORT:
+ *     The switch changes the active port.
+ * @MATE_MIXER_SWITCH_ROLE_BOOST:
+ *     The switch changes the boost value.
+ */
 typedef enum {
     MATE_MIXER_SWITCH_ROLE_UNKNOWN,
     MATE_MIXER_SWITCH_ROLE_DEVICE_PROFILE,
@@ -180,18 +279,29 @@ typedef enum {
 /**
  * MateMixerChannelPosition:
  * @MATE_MIXER_CHANNEL_UNKNOWN:
+ *     Unknown channel position.
  * @MATE_MIXER_CHANNEL_MONO:
+ *     Mono channel. Only used for single-channel controls.
  * @MATE_MIXER_CHANNEL_FRONT_LEFT:
+ *     Front left channel.
  * @MATE_MIXER_CHANNEL_FRONT_RIGHT:
+ *     Front right channel.
  * @MATE_MIXER_CHANNEL_FRONT_CENTER:
+ *     Front center channel.
  * @MATE_MIXER_CHANNEL_LFE:
+ *     Low-frequency effects channel (subwoofer).
  * @MATE_MIXER_CHANNEL_BACK_LEFT:
+ *     Back (rear) left channel.
  * @MATE_MIXER_CHANNEL_BACK_RIGHT:
+ *     Back (rear) right channel.
  * @MATE_MIXER_CHANNEL_BACK_CENTER:
+ *     Back (rear) center channel.
  * @MATE_MIXER_CHANNEL_FRONT_LEFT_CENTER:
  * @MATE_MIXER_CHANNEL_FRONT_RIGHT_CENTER:
  * @MATE_MIXER_CHANNEL_SIDE_LEFT:
+ *     Side left channel.
  * @MATE_MIXER_CHANNEL_SIDE_RIGHT:
+ *     Side right channel.
  * @MATE_MIXER_CHANNEL_TOP_FRONT_LEFT:
  * @MATE_MIXER_CHANNEL_TOP_FRONT_RIGHT:
  * @MATE_MIXER_CHANNEL_TOP_FRONT_CENTER:
@@ -221,6 +331,7 @@ typedef enum {
     MATE_MIXER_CHANNEL_TOP_BACK_LEFT,
     MATE_MIXER_CHANNEL_TOP_BACK_RIGHT,
     MATE_MIXER_CHANNEL_TOP_BACK_CENTER,
+    /*< private >*/
     MATE_MIXER_CHANNEL_MAX
 } MateMixerChannelPosition;
 
diff --git a/libmatemixer/matemixer-switch.c b/libmatemixer/matemixer-switch.c
index e50d416..a262e88 100644
--- a/libmatemixer/matemixer-switch.c
+++ b/libmatemixer/matemixer-switch.c
@@ -336,7 +336,7 @@ mate_mixer_switch_set_active_option (MateMixerSwitch       *swtch,
 }
 
 /**
- * mate_mixer_switch_get_name:
+ * mate_mixer_switch_list_options:
  * @swtch: a #MateMixerSwitch
  */
 const GList *
diff --git a/libmatemixer/matemixer.c b/libmatemixer/matemixer.c
index a5bca6f..ce39ccc 100644
--- a/libmatemixer/matemixer.c
+++ b/libmatemixer/matemixer.c
@@ -28,8 +28,8 @@
 /**
  * SECTION:matemixer
  * @short_description: Library initialization and support functions
- * @title: MateMixer
  * @include: libmatemixer/matemixer.h
+ * @see_also: #MateMixerContext
  */
 
 static void       load_modules     (void);