Documentation additions and fixes

8 files changed, 246 insertions, 37 deletions

diff --git a/docs/reference/libmatemixer-sections.txt b/docs/reference/libmatemixer-sections.txt
index 2b901e5..d3545f6 100644
--- a/docs/reference/libmatemixer-sections.txt
+++ b/docs/reference/libmatemixer-sections.txt
@@ -59,9 +59,9 @@ MATE_MIXER_CONTEXT_GET_CLASS
 MATE_MIXER_IS_CONTEXT
 MATE_MIXER_IS_CONTEXT_CLASS
 MATE_MIXER_TYPE_CONTEXT
-mate_mixer_context_get_type
 <SUBSECTION Private>
 MateMixerContextPrivate
+mate_mixer_context_get_type
 </SECTION>
 
 <SECTION>
@@ -83,9 +83,9 @@ MATE_MIXER_DEVICE_GET_CLASS
 MATE_MIXER_IS_DEVICE
 MATE_MIXER_IS_DEVICE_CLASS
 MATE_MIXER_TYPE_DEVICE
-mate_mixer_device_get_type
 <SUBSECTION Private>
 MateMixerDevicePrivate
+mate_mixer_device_get_type
 </SECTION>
 
 <SECTION>
@@ -98,6 +98,7 @@ MATE_MIXER_IS_STORED_CONTROL
 MATE_MIXER_STORED_CONTROL
 MATE_MIXER_STORED_CONTROL_GET_INTERFACE
 MATE_MIXER_TYPE_STORED_CONTROL
+<SUBSECTION Private>
 mate_mixer_stored_control_get_type
 </SECTION>
 
@@ -116,7 +117,6 @@ mate_mixer_stream_get_switch
 mate_mixer_stream_get_default_control
 mate_mixer_stream_list_controls
 mate_mixer_stream_list_switches
-MateMixerStreamPrivate
 <SUBSECTION Standard>
 MATE_MIXER_IS_STREAM
 MATE_MIXER_IS_STREAM_CLASS
@@ -124,6 +124,8 @@ MATE_MIXER_STREAM
 MATE_MIXER_STREAM_CLASS
 MATE_MIXER_STREAM_GET_CLASS
 MATE_MIXER_TYPE_STREAM
+<SUBSECTION Private>
+MateMixerStreamPrivate
 mate_mixer_stream_get_type
 </SECTION>
 
@@ -168,7 +170,6 @@ mate_mixer_stream_control_get_min_volume
 mate_mixer_stream_control_get_max_volume
 mate_mixer_stream_control_get_normal_volume
 mate_mixer_stream_control_get_base_volume
-MateMixerStreamControlPrivate
 <SUBSECTION Standard>
 MATE_MIXER_IS_STREAM_CONTROL
 MATE_MIXER_IS_STREAM_CONTROL_CLASS
@@ -176,6 +177,8 @@ MATE_MIXER_STREAM_CONTROL
 MATE_MIXER_STREAM_CONTROL_CLASS
 MATE_MIXER_STREAM_CONTROL_GET_CLASS
 MATE_MIXER_TYPE_STREAM_CONTROL
+<SUBSECTION Private>
+MateMixerStreamControlPrivate
 mate_mixer_stream_control_get_type
 </SECTION>
 
@@ -194,7 +197,6 @@ mate_mixer_switch_get_option
 mate_mixer_switch_list_options
 mate_mixer_switch_get_active_option
 mate_mixer_switch_set_active_option
-MateMixerSwitchPrivate
 <SUBSECTION Standard>
 MATE_MIXER_IS_SWITCH
 MATE_MIXER_IS_SWITCH_CLASS
@@ -202,6 +204,8 @@ MATE_MIXER_SWITCH
 MATE_MIXER_SWITCH_CLASS
 MATE_MIXER_SWITCH_GET_CLASS
 MATE_MIXER_TYPE_SWITCH
+<SUBSECTION Private>
+MateMixerSwitchPrivate
 mate_mixer_switch_get_type
 </SECTION>
 
@@ -213,7 +217,6 @@ MateMixerSwitchOptionClass
 mate_mixer_switch_option_get_name
 mate_mixer_switch_option_get_label
 mate_mixer_switch_option_get_icon
-MateMixerSwitchOptionPrivate
 <SUBSECTION Standard>
 MATE_MIXER_IS_SWITCH_OPTION
 MATE_MIXER_IS_SWITCH_OPTION_CLASS
@@ -221,6 +224,8 @@ MATE_MIXER_SWITCH_OPTION
 MATE_MIXER_SWITCH_OPTION_CLASS
 MATE_MIXER_SWITCH_OPTION_GET_CLASS
 MATE_MIXER_TYPE_SWITCH_OPTION
+<SUBSECTION Private>
+MateMixerSwitchOptionPrivate
 mate_mixer_switch_option_get_type
 </SECTION>
 
@@ -232,7 +237,6 @@ MateMixerToggleClass
 mate_mixer_toggle_get_state
 mate_mixer_toggle_set_state
 mate_mixer_toggle_get_state_option
-MateMixerTogglePrivate
 <SUBSECTION Standard>
 MATE_MIXER_IS_TOGGLE
 MATE_MIXER_IS_TOGGLE_CLASS
@@ -240,5 +244,7 @@ MATE_MIXER_TOGGLE
 MATE_MIXER_TOGGLE_CLASS
 MATE_MIXER_TOGGLE_GET_CLASS
 MATE_MIXER_TYPE_TOGGLE
+<SUBSECTION Private>
+MateMixerTogglePrivate
 mate_mixer_toggle_get_type
 </SECTION>
diff --git a/libmatemixer/matemixer-context.c b/libmatemixer/matemixer-context.c
index bb24416..0251d97 100644
--- a/libmatemixer/matemixer-context.c
+++ b/libmatemixer/matemixer-context.c
@@ -32,6 +32,43 @@
  * SECTION:matemixer-context
  * @short_description:The main class for interfacing with the library
  * @include: libmatemixer/matemixer.h
+ *
+ * After the library is initialized, a context should be created to gain
+ * access to a sound system.
+ *
+ * To create a new context, use the mate_mixer_context_new() function.
+ *
+ * The mate_mixer_context_set_backend_type() function can be used to associate
+ * the context with a particular type of sound system. Using this function is
+ * not necessary, by default the context will select a working sound system
+ * backend automatically.
+ *
+ * To connect to a sound system, use mate_mixer_context_open().
+ *
+ * When the connection is established, it is possible to query a list of sound
+ * devices with mate_mixer_context_list_devices() and streams with
+ * mate_mixer_context_list_streams().
+ *
+ * A device represents a hardware or software sound device in the system,
+ * typically a sound card.
+ *
+ * A stream is an input or output channel that may exist either as a part of a
+ * sound device, or independently. Streams essentially serve as containers for
+ * volume controls and switches, for example a sound card with microphone and
+ * line-in connectors may have an input stream containing volume controls for
+ * each of these connectors and possibly a switch allowing to change the active
+ * connector.
+ *
+ * Streams may also exist independently as the sound system may for example
+ * allow audio streaming over a network.
+ *
+ * For a more thorough description of devices and streams, see #MateMixerDevice
+ * and #MateMixerStream.
+ *
+ * Devices and streams (as almost all other elements in the library) may appear
+ * and disappear at any time, for example when external sound cards are plugged
+ * and unplugged. The application should connect to the appropriate signals to
+ * handle these events.
  */
 
 struct _MateMixerContextPrivate
@@ -545,11 +582,15 @@ mate_mixer_context_new (void)
  * be used to alter this behavior and make the @context use the selected sound
  * system.
  *
+ * Setting the sound system backend only succeeds if the selected backend module
+ * is available in the target 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.
  */
+// XXX handle UNKNOWN
 gboolean
 mate_mixer_context_set_backend_type (MateMixerContext     *context,
                                      MateMixerBackendType  backend_type)
@@ -747,9 +788,9 @@ mate_mixer_context_set_server_address (MateMixerContext *context, const gchar *a
  * 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.
+ * #MateMixerContext:state after this function returns.
  *
- * The %MATE_MIXER_STATE_READY state indicates, that the connection has been
+ * The %MATE_MIXER_STATE_READY state indicates that the connection has been
  * established successfully.
  *
  * The %MATE_MIXER_STATE_CONNECTING state is reached when the connection has not been
@@ -1130,8 +1171,9 @@ 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 sound system 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 the @context is connected to a sound system.
  *
  * Returns: the name or %NULL on error.
  */
@@ -1150,8 +1192,9 @@ mate_mixer_context_get_backend_name (MateMixerContext *context)
  * mate_mixer_context_get_backend_type:
  * @context: a #MateMixerContext
  *
- * Gets the type of the currently used sound system 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 the @context is connected to a sound system.
  *
  * Returns: the backend type or %MATE_MIXER_BACKEND_UNKNOWN on error.
  */
@@ -1170,8 +1213,9 @@ 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.
+ * Gets the capability flags of the currently used sound system backend.
+ *
+ * This function will not work until the @context is connected to a sound system.
  *
  * Returns: the capability flags.
  */
diff --git a/libmatemixer/matemixer-device.c b/libmatemixer/matemixer-device.c
index 9206833..f45f9b9 100644
--- a/libmatemixer/matemixer-device.c
+++ b/libmatemixer/matemixer-device.c
@@ -27,6 +27,10 @@
  * SECTION:matemixer-device
  * @short_description: Hardware or software device in the sound system
  * @include: libmatemixer/matemixer.h
+ *
+ * A #MateMixerDevice represents a sound device, most typically a sound card.
+ *
+ * Each device may contain an arbitrary number of streams.
  */
 
 struct _MateMixerDevicePrivate
@@ -95,7 +99,6 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass)
      *
      * 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",
@@ -311,8 +314,10 @@ 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.
+ * 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
@@ -332,8 +337,10 @@ 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.
+ * 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.
  */
@@ -351,7 +358,7 @@ mate_mixer_device_get_label (MateMixerDevice *device)
  *
  * Gets the XDG icon name of the device.
  *
- * Returns: the icon name.
+ * Returns: the icon name or %NULL.
  */
 const gchar *
 mate_mixer_device_get_icon (MateMixerDevice *device)
diff --git a/libmatemixer/matemixer-enums.h b/libmatemixer/matemixer-enums.h
index 601dc86..96176fa 100644
--- a/libmatemixer/matemixer-enums.h
+++ b/libmatemixer/matemixer-enums.h
@@ -30,7 +30,7 @@
  * @MATE_MIXER_STATE_CONNECTING:
  *     Connection is in progress.
  * @MATE_MIXER_STATE_READY:
- *     Connected successfully.
+ *     Connected.
  * @MATE_MIXER_STATE_FAILED:
  *     Connection has failed.
  * @MATE_MIXER_STATE_UNKNOWN:
@@ -49,7 +49,7 @@ typedef enum {
 /**
  * MateMixerBackendType:
  * @MATE_MIXER_BACKEND_UNKNOWN:
- *     Unknown or undefined backend type.
+ *     Unknown or undefined sound system backend type.
  * @MATE_MIXER_BACKEND_PULSEAUDIO:
  *     PulseAudio sound system backend. It has the highest priority and
  *     will be the first one to try when you call mate_mixer_context_open(),
@@ -79,11 +79,13 @@ typedef enum {
  * @MATE_MIXER_BACKEND_NO_FLAGS:
  *     No flags.
  * @MATE_MIXER_BACKEND_HAS_APPLICATION_CONTROLS:
- *     The sound system backend includes support for application stream controls.
+ *     The sound system backend includes support for application stream controls,
+ *     allowing per-application volume control.
  * @MATE_MIXER_BACKEND_HAS_STORED_CONTROLS:
- *     The sound system backend includes support for stored controls. The presence
- *     of this flag does not guarantee that this feature is enabled in the sound
- *     system's configuration.
+ *     The sound system backend includes support for stored controls. See the
+ *     #MateMixerStoredControl description for more information.
+ *     The presence of this flag does not guarantee that this feature is enabled
+ *     in the sound system's configuration.
  * @MATE_MIXER_BACKEND_CAN_SET_DEFAULT_INPUT_STREAM:
  *     The sound system backend is able to change the current default input stream
  *     using the mate_mixer_context_set_default_input_stream() function.
@@ -214,8 +216,11 @@ typedef enum {
  * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_UNKNOWN:
  *     Unknown media role.
  * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_VIDEO:
+ *     Video role.
  * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_MUSIC:
+ *     Music role.
  * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_GAME:
+ *     Game role.
  * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_EVENT:
  *     Event sounds.
  * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_PHONE:
@@ -227,13 +232,16 @@ typedef enum {
  * @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.
+ * to PulseAudio media role property and therefore are 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).
+ *
+ * See the PulseAudio documentation for more detailed information about media
+ * roles.
  */
 typedef enum {
     MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_UNKNOWN,
@@ -302,18 +310,27 @@ typedef enum {
  * @MATE_MIXER_CHANNEL_BACK_CENTER:
  *     Back (rear) center channel.
  * @MATE_MIXER_CHANNEL_FRONT_LEFT_CENTER:
+ *     Front left of center channel.
  * @MATE_MIXER_CHANNEL_FRONT_RIGHT_CENTER:
+ *     Front right of center channel.
  * @MATE_MIXER_CHANNEL_SIDE_LEFT:
  *     Side left channel.
  * @MATE_MIXER_CHANNEL_SIDE_RIGHT:
  *     Side right channel.
  * @MATE_MIXER_CHANNEL_TOP_FRONT_LEFT:
+ *     Top front left channel.
  * @MATE_MIXER_CHANNEL_TOP_FRONT_RIGHT:
+ *     Top front right channel.
  * @MATE_MIXER_CHANNEL_TOP_FRONT_CENTER:
+ *     Top front center channel.
  * @MATE_MIXER_CHANNEL_TOP_CENTER:
+ *     Top center channel.
  * @MATE_MIXER_CHANNEL_TOP_BACK_LEFT:
+ *     Top back (rear) left channel.
  * @MATE_MIXER_CHANNEL_TOP_BACK_RIGHT:
+ *     Top back (rear) right channel.
  * @MATE_MIXER_CHANNEL_TOP_BACK_CENTER:
+ *     Top back (rear) center channel.
  */
 typedef enum {
     MATE_MIXER_CHANNEL_UNKNOWN = 0,
diff --git a/libmatemixer/matemixer-switch-option.c b/libmatemixer/matemixer-switch-option.c
index b20f92b..4c0e0fa 100644
--- a/libmatemixer/matemixer-switch-option.c
+++ b/libmatemixer/matemixer-switch-option.c
@@ -69,6 +69,12 @@ mate_mixer_switch_option_class_init (MateMixerSwitchOptionClass *klass)
     object_class->get_property = mate_mixer_switch_option_get_property;
     object_class->set_property = mate_mixer_switch_option_set_property;
 
+    /**
+     * MateMixerSwitchOption:name:
+     *
+     * The name of the switch option. 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",
@@ -78,6 +84,12 @@ mate_mixer_switch_option_class_init (MateMixerSwitchOptionClass *klass)
                              G_PARAM_CONSTRUCT_ONLY |
                              G_PARAM_STATIC_STRINGS);
 
+    /**
+     * MateMixerSwitchOption:label:
+     *
+     * The label of the switch option. 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",
@@ -87,6 +99,11 @@ mate_mixer_switch_option_class_init (MateMixerSwitchOptionClass *klass)
                              G_PARAM_CONSTRUCT_ONLY |
                              G_PARAM_STATIC_STRINGS);
 
+    /**
+     * MateMixerSwitchOption:icon:
+     *
+     * The XDG icon name of the switch option.
+     */
     properties[PROP_ICON] =
         g_param_spec_string ("icon",
                              "Icon",
@@ -183,6 +200,15 @@ mate_mixer_switch_option_finalize (GObject *object)
 /**
  * mate_mixer_switch_option_get_name:
  * @option: a #MateMixerSwitchOption
+ *
+ * Gets the name of the switch option. 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 switch options
+ * of a particular #MateMixerSwitch and may be used to get the #MateMixerSwitchOption
+ * using mate_mixer_switch_get_option().
+ *
+ * Returns: the name of the switch option.
  */
 const gchar *
 mate_mixer_switch_option_get_name (MateMixerSwitchOption *option)
@@ -195,6 +221,11 @@ mate_mixer_switch_option_get_name (MateMixerSwitchOption *option)
 /**
  * mate_mixer_switch_option_get_label:
  * @option: a #MateMixerSwitchOption
+ *
+ * Gets the label of the switch option. This is a potentially translated string
+ * that should be presented to users in the user interface.
+ *
+ * Returns: the label of the switch option.
  */
 const gchar *
 mate_mixer_switch_option_get_label (MateMixerSwitchOption *option)
@@ -207,6 +238,10 @@ mate_mixer_switch_option_get_label (MateMixerSwitchOption *option)
 /**
  * mate_mixer_switch_option_get_icon:
  * @option: a #MateMixerSwitchOption
+ *
+ * Gets the XDG icon name of the switch option.
+ *
+ * Returns: the icon name or %NULL.
  */
 const gchar *
 mate_mixer_switch_option_get_icon (MateMixerSwitchOption *option)
diff --git a/libmatemixer/matemixer-switch.c b/libmatemixer/matemixer-switch.c
index a262e88..926c9a6 100644
--- a/libmatemixer/matemixer-switch.c
+++ b/libmatemixer/matemixer-switch.c
@@ -241,6 +241,13 @@ mate_mixer_switch_finalize (GObject *object)
 /**
  * mate_mixer_switch_get_name:
  * @swtch: a #MateMixerSwitch
+ *
+ * Gets the name of the switch.
+ *
+ * The name serves as a unique identifier and in most cases it is not in a
+ * user-readable form.
+ *
+ * Returns: the name of the switch.
  */
 const gchar *
 mate_mixer_switch_get_name (MateMixerSwitch *swtch)
@@ -253,6 +260,13 @@ mate_mixer_switch_get_name (MateMixerSwitch *swtch)
 /**
  * mate_mixer_switch_get_label:
  * @swtch: a #MateMixerSwitch
+ *
+ * Gets the label of the switch.
+ *
+ * This is a potentially translated string that should be presented to users
+ * in the user interface.
+ *
+ * Returns: the label of the switch option.
  */
 const gchar *
 mate_mixer_switch_get_label (MateMixerSwitch *swtch)
@@ -265,6 +279,11 @@ mate_mixer_switch_get_label (MateMixerSwitch *swtch)
 /**
  * mate_mixer_switch_get_flags:
  * @swtch: a #MateMixerSwitch
+ *
+ * Gets the flags of the switch. See #MateMixerSwitchFlags for information about
+ * the meaning of the individual flags.
+ *
+ * Returns: the flags of the switch.
  */
 MateMixerSwitchFlags
 mate_mixer_switch_get_flags (MateMixerSwitch *swtch)
@@ -277,6 +296,11 @@ mate_mixer_switch_get_flags (MateMixerSwitch *swtch)
 /**
  * mate_mixer_switch_get_role:
  * @swtch: a #MateMixerSwitch
+ *
+ * Gets the role of the switch. The role identifies the purpose of the switch.
+
+ * Note that while the role identification should be reliable, it may be based on
+ * looking for well-known switch names on some sound systems.
  */
 MateMixerSwitchRole
 mate_mixer_switch_get_role (MateMixerSwitch *swtch)
@@ -290,6 +314,10 @@ mate_mixer_switch_get_role (MateMixerSwitch *swtch)
  * mate_mixer_switch_get_option:
  * @swtch: a #MateMixerSwitch
  * @name: the name of an option
+ *
+ * Gets the #MateMixerSwitchOption with the given name.
+ *
+ * Returns: a #MateMixerSwitchOption or %NULL if there is no such switch option.
  */
 MateMixerSwitchOption *
 mate_mixer_switch_get_option (MateMixerSwitch *swtch, const gchar *name)
@@ -302,6 +330,10 @@ mate_mixer_switch_get_option (MateMixerSwitch *swtch, const gchar *name)
 /**
  * mate_mixer_switch_get_active_option:
  * @swtch: a #MateMixerSwitch
+ *
+ * Gets the #MateMixerSwitchOption which is currently active.
+ *
+ * Returns: a #MateMixerSwitchOption.
  */
 MateMixerSwitchOption *
 mate_mixer_switch_get_active_option (MateMixerSwitch *swtch)
@@ -315,6 +347,10 @@ mate_mixer_switch_get_active_option (MateMixerSwitch *swtch)
  * mate_mixer_switch_set_active_option:
  * @swtch: a #MateMixerSwitch
  * @option: the #MateMixerSwitchOption to set as the active option
+ *
+ * Changes the currently active switch option.
+ *
+ * Returns: %TRUE on success or %FALSE on failure.
  */
 gboolean
 mate_mixer_switch_set_active_option (MateMixerSwitch       *swtch,
@@ -338,6 +374,13 @@ mate_mixer_switch_set_active_option (MateMixerSwitch       *swtch,
 /**
  * mate_mixer_switch_list_options:
  * @swtch: a #MateMixerSwitch
+ *
+ * Gets the list of switch options that belong to the switch.
+ *
+ * The returned #GList is owned by the #MateMixerSwitch and may be invalidated
+ * at any time.
+ *
+ * Returns: a #GList of the switch options.
  */
 const GList *
 mate_mixer_switch_list_options (MateMixerSwitch *swtch)
diff --git a/libmatemixer/matemixer-toggle.c b/libmatemixer/matemixer-toggle.c
index 869807a..5a85076 100644
--- a/libmatemixer/matemixer-toggle.c
+++ b/libmatemixer/matemixer-toggle.c
@@ -24,6 +24,7 @@
 
 /**
  * SECTION:matemixer-toggle
+ * @short_description: On/Off switch
  * @include: libmatemixer/matemixer.h
  */
 
@@ -80,6 +81,12 @@ mate_mixer_toggle_class_init (MateMixerToggleClass *klass)
     switch_class->get_option   = mate_mixer_toggle_get_option;
     switch_class->list_options = mate_mixer_toggle_list_options;
 
+    /**
+     * MateMixerToggle:state:
+     *
+     * The current state of the toggle. %TRUE corresponds to the 'on' state and
+     * %FALSE to the 'off' state.
+     */
     properties[PROP_STATE] =
         g_param_spec_boolean ("state",
                               "State",
@@ -88,19 +95,29 @@ mate_mixer_toggle_class_init (MateMixerToggleClass *klass)
                               G_PARAM_READABLE |
                               G_PARAM_STATIC_STRINGS);
 
+    /**
+     * MateMixerToggle:on-state-option:
+     *
+     * The #MateMixerSwitchOption representing the 'on' value of the toggle.
+     */
     properties[PROP_ON_STATE_OPTION] =
         g_param_spec_object ("on-state-option",
-                             "State option for on",
-                             "Option corresponding to the 'on' value of the toggle",
+                             "On state option",
+                             "On state option",
                              MATE_MIXER_TYPE_SWITCH_OPTION,
                              G_PARAM_READWRITE |
                              G_PARAM_CONSTRUCT_ONLY |
                              G_PARAM_STATIC_STRINGS);
 
+    /**
+     * MateMixerToggle:off-state-option:
+     *
+     * The #MateMixerSwitchOption representing the 'off' value of the toggle.
+     */
     properties[PROP_OFF_STATE_OPTION] =
         g_param_spec_object ("off-state-option",
-                             "State option for off",
-                             "Option corresponding to the 'off' value of the toggle",
+                             "Off state option",
+                             "Off state option",
                              MATE_MIXER_TYPE_SWITCH_OPTION,
                              G_PARAM_READWRITE |
                              G_PARAM_CONSTRUCT_ONLY |
@@ -193,6 +210,11 @@ mate_mixer_toggle_dispose (GObject *object)
 /**
  * mate_mixer_toggle_get_state:
  * @toggle: a #MateMixerToggle
+ *
+ * Gets the current state of the toggle. %TRUE corresponds to the 'on' state and
+ * %FALSE to the 'off' state.
+ *
+ * Returns: %TRUE or %FALSE.
  */
 gboolean
 mate_mixer_toggle_get_state (MateMixerToggle *toggle)
@@ -214,7 +236,11 @@ mate_mixer_toggle_get_state (MateMixerToggle *toggle)
 /**
  * mate_mixer_toggle_get_state_option:
  * @toggle: a #MateMixerToggle
- * @state: the state to retrieve
+ * @state: the state to get the #MateMixerSwitchOption for
+ *
+ * Gets the #MateMixerSwitchOption representing the selected state.
+ *
+ * Returns: a #MateMixerSwitchOption.
  */
 MateMixerSwitchOption *
 mate_mixer_toggle_get_state_option (MateMixerToggle *toggle, gboolean state)
@@ -231,6 +257,13 @@ mate_mixer_toggle_get_state_option (MateMixerToggle *toggle, gboolean state)
  * mate_mixer_toggle_set_state:
  * @toggle: a #MateMixerToggle
  * @state: the state to set
+ *
+ * Sets the @toggle to the selected state.
+ *
+ * This function is equivalent to using mate_mixer_switch_set_active_option()
+ * with a #MateMixerSwitchOption representing the selected state.
+ *
+ * Returns: %TRUE on success or %FALSE on failure.
  */
 gboolean
 mate_mixer_toggle_set_state (MateMixerToggle *toggle, gboolean state)
diff --git a/libmatemixer/matemixer.c b/libmatemixer/matemixer.c
index ce39ccc..51dc029 100644
--- a/libmatemixer/matemixer.c
+++ b/libmatemixer/matemixer.c
@@ -30,6 +30,15 @@
  * @short_description: Library initialization and support functions
  * @include: libmatemixer/matemixer.h
  * @see_also: #MateMixerContext
+ *
+ * The libmatemixer library must be initialized before it is used by an
+ * application. The initialization function loads dynamic modules which provide
+ * access to sound systems (also called backends) and it only succeeds if there
+ * is at least one usable module present on the target system.
+ *
+ * To connect to a sound system and access the mixer functionality after the
+ * library is initialized, create a #MateMixerContext using the
+ * mate_mixer_context_new() function.
  */
 
 static void       load_modules     (void);
@@ -100,14 +109,28 @@ mate_mixer_is_initialized (void)
     return initialized;
 }
 
-/* Internal: return a list of loaded backend modules */
+/**
+ * _mate_mixer_list_modules:
+ *
+ * Gets a list of loaded backend modules.
+ *
+ * Returns: a #GList.
+ */
 const GList *
 _mate_mixer_list_modules (void)
 {
     return (const GList *) modules;
 }
 
-/* Internal: create a channel mask using the given list of channel positions */
+/**
+ * _mate_mixer_create_channel_mask:
+ * @positions: an array of channel positions
+ * @n: number of channel positions in the array
+ *
+ * Creates a channel mask using the given list of channel positions.
+ *
+ * Returns: a channel mask.
+ */
 guint32
 _mate_mixer_create_channel_mask (MateMixerChannelPosition *positions, guint n)
 {
@@ -164,7 +187,8 @@ load_modules (void)
     loaded = TRUE;
 }
 
-/* Backend modules sorting function, higher priority number means higher priority */
+/* Backend modules sorting function, higher priority number means higher priority
+ * of the backend module */
 static gint
 compare_modules (gconstpointer a, gconstpointer b)
 {