[PATCH v3 3/6] doc: trivial fixes

[Víctor Manuel Jáquez Leal <vjaquez igalia com>]

Honor 80 char per line and other small fixes.

Signed-off-by: Víctor Manuel Jáquez Leal <vjaquez igalia com>
---
 src/grl-media-source.c    |   46 ++++++++++++++++++++++++++++++--------------
 src/grl-media-source.h    |   10 ++++----
 src/grl-plugin-registry.c |   16 +++++++++-----
 3 files changed, 46 insertions(+), 26 deletions(-)

diff --git a/src/grl-media-source.c b/src/grl-media-source.c
index 020aa0f..c5730c4 100644
--- a/src/grl-media-source.c
+++ b/src/grl-media-source.c
@@ -1186,7 +1186,8 @@ metadata_full_resolution_ctl_cb (GrlMediaSource *source,
  * grl_media_source_browse:
  * @source: a media source
  * @container: (allow-none): a container of data transfer objects
- * @keys: (element-type GObject.ParamSpec) (transfer none): the list of #GrlKeyID to request
+ * @keys: (element-type GObject.ParamSpec) (transfer none): the #GList of
+ * #GrlKeyID<!-- -->s to request
  * @skip: the number if elements to skip in the browse operation
  * @count: the number of elements to retrieve in the browse operation
  * @flags: the resolution mode
@@ -1322,17 +1323,21 @@ grl_media_source_browse (GrlMediaSource *source,
  * grl_media_source_browse_sync:
  * @source: a media source
  * @container: (allow-none): a container of data transfer objects
- * @keys: (element-type GObject.ParamSpec) (transfer none): the list of #GrlKeyID to request
+ * @keys: (element-type GObject.ParamSpec) (transfer none): the #GList of
+ * #GrlKeyID<!-- -->s to request
  * @skip: the number if elements to skip in the browse operation
  * @count: the number of elements to retrieve in the browse operation
  * @flags: the resolution mode
  * @error: a #GError, or @NULL
  *
- * Browse from @skip, a @count number of media elements through an available list.
+ * Browse from @skip, a @count number of media elements through an available
+ * list.
  *
  * This method is synchronous.
  *
- * Returns: (element-type Grl.Media) (transfer full): a list with #GrlMedia elements
+ * Returns: (element-type Grl.Media) (transfer full): a #GList with #GrlMedia
+ * elements. After use g_object_unref() every element and g_list_free() the
+ * list.
  */
 GList *
 grl_media_source_browse_sync (GrlMediaSource *source,
@@ -1377,7 +1382,8 @@ grl_media_source_browse_sync (GrlMediaSource *source,
  * grl_media_source_search:
  * @source: a media source
  * @text: the text to search
- * @keys: (element-type GObject.ParamSpec) (transfer none): the list of #GrlKeyID to request
+ * @keys: (element-type GObject.ParamSpec) (transfer none): the #GList of
+ * #GrlKeyID<!-- -->s to request
  * @skip: the number if elements to skip in the search operation
  * @count: the number of elements to retrieve in the search operation
  * @flags: the resolution mode
@@ -1503,7 +1509,8 @@ grl_media_source_search (GrlMediaSource *source,
  * grl_media_source_search_sync:
  * @source: a media source
  * @text: the text to search
- * @keys: (element-type GObject.ParamSpec) (transfer none): the list of #GrlKeyID to request
+ * @keys: (element-type GObject.ParamSpec) (transfer none): the #GList of
+ * #GrlKeyID<!-- -->s to request
  * @skip: the number if elements to skip in the search operation
  * @count: the number of elements to retrieve in the search operation
  * @flags: the resolution mode
@@ -1514,7 +1521,9 @@ grl_media_source_search (GrlMediaSource *source,
  *
  * This method is synchronous.
  *
- * Returns: (element-type Grl.Media) (transfer full): a list with #GrlMedia elements
+ * Returns: (element-type Grl.Media) (transfer full): a #GList with #GrlMedia
+ * elements. After use g_object_unref() every element and g_list_free() the
+ * list.
  */
 GList *
 grl_media_source_search_sync (GrlMediaSource *source,
@@ -1559,7 +1568,8 @@ grl_media_source_search_sync (GrlMediaSource *source,
  * grl_media_source_query:
  * @source: a media source
  * @query: the query to process
- * @keys: (element-type GObject.ParamSpec) (transfer none): the list of #GrlKeyID to request
+ * @keys: (element-type GObject.ParamSpec) (transfer none): the #GList of
+ * #GrlKeyID<!-- -->s to request
  * @skip: the number if elements to skip in the query operation
  * @count: the number of elements to retrieve in the query operation
  * @flags: the resolution mode
@@ -1691,7 +1701,8 @@ grl_media_source_query (GrlMediaSource *source,
  * grl_media_source_query_sync:
  * @source: a media source
  * @query: the query to process
- * @keys: (element-type GObject.ParamSpec) (transfer none):the list of #GrlKeyID to request
+ * @keys: (element-type GObject.ParamSpec) (transfer none): the #GList of
+ * #GrlKeyID<!-- -->s to request
  * @skip: the number if elements to skip in the query operation
  * @count: the number of elements to retrieve in the query operation
  * @flags: the resolution mode
@@ -1702,7 +1713,9 @@ grl_media_source_query (GrlMediaSource *source,
  *
  * This method is synchronous.
  *
- * Returns: (element-type Grl.Media) (transfer full): a list with #GrlMedia elements
+ * Returns: (element-type Grl.Media) (transfer full): a #GList with #GrlMedia
+ * elements. After use g_object_unref() every element and g_list_free() the
+ * list.
  */
 GList *
 grl_media_source_query_sync (GrlMediaSource *source,
@@ -1747,7 +1760,8 @@ grl_media_source_query_sync (GrlMediaSource *source,
  * grl_media_source_metadata:
  * @source: a media source
  * @media: (allow-none): a data transfer object
- * @keys: (element-type GObject.ParamSpec) (transfer none): the list of #GrlKeyID to request
+ * @keys: (element-type GObject.ParamSpec) (transfer none): the #GList of
+ * #GrlKeyID<!-- -->s to request
  * @flags: the resolution mode
  * @callback: (scope notified): the user defined callback
  * @user_data: the user data to pass in the callback
@@ -1820,6 +1834,7 @@ grl_media_source_metadata (GrlMediaSource *source,
   /* Always hook an own relay callback so we can do some
      post-processing before handing out the results
      to the user */
+
   mrc = g_new0 (struct MetadataRelayCb, 1);
   mrc->user_callback = _callback;
   mrc->user_data = _user_data;
@@ -1856,7 +1871,8 @@ grl_media_source_metadata (GrlMediaSource *source,
  * grl_media_source_metadata_sync:
  * @source: a media source
  * @media: (allow-none): a data transfer object
- * @keys: (element-type GObject.ParamSpec) (transfer none): the list of #GrlKeyID to request
+ * @keys: (element-type GObject.ParamSpec) (transfer none): the #GList of
+ * #GrlKeyID<!-- -->s to request
  * @flags: the resolution mode
  * @error: a #GError, or @NULL
  *
@@ -1865,7 +1881,7 @@ grl_media_source_metadata (GrlMediaSource *source,
  *
  * This method is synchronous.
  *
- * Returns: (transfer full): the updated #GrlMedia
+ * Returns: (transfer full): a filled #GrlMedia
  */
 GrlMedia *
 grl_media_source_metadata_sync (GrlMediaSource *source,
@@ -2110,8 +2126,8 @@ grl_media_source_store (GrlMediaSource *source,
 /**
  * grl_media_source_store_sync:
  * @source: a media source
- * @parent: (allow-none): a parent to store the data transfer objects
- * @media: a data transfer object
+ * @parent: (allow-none): a #GrlMediaBox to store the data transfer objects
+ * @media: a #GrlMedia data transfer object
  * @error: a #GError, or @NULL
  *
  * Store the @media into the @parent container.
diff --git a/src/grl-media-source.h b/src/grl-media-source.h
index 5b414e1..837d675 100644
--- a/src/grl-media-source.h
+++ b/src/grl-media-source.h
@@ -113,7 +113,7 @@ typedef void (*GrlMediaSourceMetadataCb) (GrlMediaSource *source,
 /**
  * GrlMediaSourceStoreCb:
  * @source: a media source
- * @parent: TBD
+ * @parent: The #GrlMediaBox who parents the @media
  * @media: (transfer full): a data transfer object
  * @user_data: user data passed to grl_media_source_store()
  * @error: (not-error) (type uint): possible #GError generated at processing
@@ -147,7 +147,7 @@ typedef void (*GrlMediaSourceRemoveCb) (GrlMediaSource *source,
  * @source: a media source
  * @browse_id: operation identifier
  * @container: a container of data transfer objects
- * @keys: the list of #GrlKeyID to request
+ * @keys: the #GList of #GrlKeyID<!-- -->s to request
  * @skip: the number if elements to skip in the browse operation
  * @count: the number of elements to retrieve in the browse operation
  * @flags: the resolution mode
@@ -174,7 +174,7 @@ typedef struct {
  * @source: a media source
  * @search_id: operation identifier
  * @text: the text to search
- * @keys: the list of #GrlKeyID to request
+ * @keys: the #GList of #GrlKeyID<!-- -->s to request
  * @skip: the number if elements to skip in the browse operation
  * @count: the number of elements to retrieve in the browse operation
  * @flags: the resolution mode
@@ -201,7 +201,7 @@ typedef struct {
  * @source: a media source
  * @query_id: operation identifier
  * @query: the query to process
- * @keys: the list of #GrlKeyID to request
+ * @keys: the #GList of #GrlKeyID<!-- -->s to request
  * @skip: the number if elements to skip in the browse operation
  * @count: the number of elements to retrieve in the browse operation
  * @flags: the resolution mode
@@ -228,7 +228,7 @@ typedef struct {
  * @source: a media source
  * @metadata_id: operation identifier
  * @media: a data transfer object
- * @keys: the list of #GrlKeyID to request
+ * @keys: the #GList of #GrlKeyID<!-- -->s to request
  * @flags: the resolution mode
  * @callback: the user defined callback
  * @user_data: the user data to pass in the callback
diff --git a/src/grl-plugin-registry.c b/src/grl-plugin-registry.c
index eb91293..4be7b94 100644
--- a/src/grl-plugin-registry.c
+++ b/src/grl-plugin-registry.c
@@ -30,7 +30,7 @@
  * The #GrlPluginRegistry object is a list of plugins and some functions
  * for dealing with them. Each #GrlMediaPlugin is matched 1-1 with a file
  * on disk, and may or may not be loaded a given time. There only can be
- * a single instance of #GstPluginRegistry (singleton pattern).
+ * a single instance of #GrlPluginRegistry (singleton pattern).
  *
  * A #GrlMediaPlugin can hold several data sources (#GrlMetadataSource or
  * #GrlMediaSource), and #GrlPluginRegistry shall register each one of
@@ -537,8 +537,9 @@ grl_plugin_registry_lookup_source (GrlPluginRegistry *registry,
  *
  * If @ranked is %TRUE, the source list will be ordered by rank.
  *
- * Returns: (element-type Grl.MediaPlugin) (transfer container): a list of available sources.
- * Use g_list_free() when done using the list.
+ * Returns: (element-type Grl.MediaPlugin) (transfer container): a #GList of
+ * available #GrlMediaPlugins<!-- -->s. The content of the list should not be
+ * modified or freed. Use g_list_free() when done using the list.
  */
 GList *
 grl_plugin_registry_get_sources (GrlPluginRegistry *registry,
@@ -573,8 +574,9 @@ grl_plugin_registry_get_sources (GrlPluginRegistry *registry,
  *
  * If @ranked is %TRUE, the source list will be ordered by rank.
  *
- * Returns: (element-type Grl.MediaPlugin) (transfer container):  a list of available sources.
- * Use g_list_free() when done using the list.
+ * Returns: (element-type Grl.MediaPlugin) (transfer container): a #GList of
+ * available #GrlMediaPlugins<!-- -->s. The content of the list should not be
+ * modified or freed. Use g_list_free() when done using the list.
  */
 GList *
 grl_plugin_registry_get_sources_by_operations (GrlPluginRegistry *registry,
@@ -725,7 +727,9 @@ grl_plugin_registry_lookup_metadata_key (GrlPluginRegistry *registry,
  *
  * Returns a list with all registered keys in system.
  *
- * Returns: (element-type GObject.ParamSpec) (transfer container): a list with all keys
+ * Returns: (element-type GObject.ParamSpec) (transfer container): a #GList
+ * with all the available #GrlKeyID<!-- -->s. The content of the list should
+ * not be modified or freed. Use g_list_free() when done using the list.
  **/
 GList *
 grl_plugin_registry_get_metadata_keys (GrlPluginRegistry *registry)
-- 
1.7.1