Documentation additions and fixes

author: Michal Ratajsky <[email protected]> 2014-09-05 16:36:05 +0200
committer: Michal Ratajsky <[email protected]> 2014-09-05 16:36:05 +0200
commit: 1a9410a38aebb6ce05d43433c020e198416761df (patch)
tree: b2db9e589c88585063101d87388fd515217214de
parent: b100e0045c0cb0b60bc381bc99dca18db82f3eba (diff)
download: libmatemixer-1a9410a38aebb6ce05d43433c020e198416761df.tar.bz2
libmatemixer-1a9410a38aebb6ce05d43433c020e198416761df.tar.xz
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)
 {
author	Michal Ratajsky <[email protected]>	2014-09-05 16:36:05 +0200
committer	Michal Ratajsky <[email protected]>	2014-09-05 16:36:05 +0200
commit	1a9410a38aebb6ce05d43433c020e198416761df (patch)
tree	b2db9e589c88585063101d87388fd515217214de
parent	b100e0045c0cb0b60bc381bc99dca18db82f3eba (diff)
download	libmatemixer-1a9410a38aebb6ce05d43433c020e198416761df.tar.bz2 libmatemixer-1a9410a38aebb6ce05d43433c020e198416761df.tar.xz