Documentation additions and fixes

author: Michal Ratajsky <[email protected]> 2014-08-28 23:39:33 +0200
committer: Michal Ratajsky <[email protected]> 2014-08-28 23:39:33 +0200
commit: 4f089f8489e292ced05a89ec7d761b9bc6533b84 (patch)
tree: 77a81710ffb092661a8df6bb92b6017b71a9b23d /libmatemixer
parent: b6955dd78085d642f10325ec6d929e7421224d74 (diff)
download: libmatemixer-4f089f8489e292ced05a89ec7d761b9bc6533b84.tar.bz2
libmatemixer-4f089f8489e292ced05a89ec7d761b9bc6533b84.tar.xz
7 files changed, 460 insertions, 85 deletions
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);
author	Michal Ratajsky <[email protected]>	2014-08-28 23:39:33 +0200
committer	Michal Ratajsky <[email protected]>	2014-08-28 23:39:33 +0200
commit	4f089f8489e292ced05a89ec7d761b9bc6533b84 (patch)
tree	77a81710ffb092661a8df6bb92b6017b71a9b23d /libmatemixer
parent	b6955dd78085d642f10325ec6d929e7421224d74 (diff)
download	libmatemixer-4f089f8489e292ced05a89ec7d761b9bc6533b84.tar.bz2 libmatemixer-4f089f8489e292ced05a89ec7d761b9bc6533b84.tar.xz