[grilo] doc: various documentation fixes.

[Iago Toral Quiroga <itoral src gnome org>]

commit 7c0118224e46682a6cca669d69f568975f2f73e6
Author: Iago Toral Quiroga <itoral igalia com>
Date:   Tue Sep 14 11:03:29 2010 +0200

    doc: various documentation fixes.

 src/data/grl-media-image.c |    4 ++--
 src/data/grl-media.c       |    4 +++-
 src/grl-metadata-source.c  |    4 ++--
 src/grl-metadata-source.h  |   21 +++++++++++----------
 src/grl-multiple.c         |    2 +-
 src/grl-plugin-registry.h  |    1 +
 6 files changed, 20 insertions(+), 16 deletions(-)
---
diff --git a/src/data/grl-media-image.c b/src/data/grl-media-image.c
index 9881bde..7e36f13 100644
--- a/src/data/grl-media-image.c
+++ b/src/data/grl-media-image.c
@@ -130,7 +130,7 @@ grl_media_image_set_height (GrlMediaImage *data, gint height)
  * grl_media_image_get_width:
  * @data: The image instance
  *
- * Return: the width of the image
+ * Returns: the width of the image
  */
 gint
 grl_media_image_get_width (GrlMediaImage *data)
@@ -142,7 +142,7 @@ grl_media_image_get_width (GrlMediaImage *data)
  * grl_media_image_get_height:
  * @data: the image instance
  *
- * Return: the height of the image
+ * Returns: the height of the image
  */
 gint
 grl_media_image_get_height (GrlMediaImage *data)
diff --git a/src/data/grl-media.c b/src/data/grl-media.c
index fb3c085..7907777 100644
--- a/src/data/grl-media.c
+++ b/src/data/grl-media.c
@@ -575,6 +575,7 @@ grl_media_set_last_position (GrlMedia *data, gint last_position)
 /**
  * grl_media_set_external_player:
  * @data: the media
+ * @player: location of an external player for this media
  *
  * Set the location of a player for the media (usually a flash player)
  */
@@ -589,6 +590,7 @@ grl_media_set_external_player (GrlMedia *data, const gchar *player)
 /**
  * grl_media_set_external_url:
  * @data: the media
+ * @url: external location where this media can be played.
  *
  * Set an external location where users can play the media
  */
@@ -633,7 +635,7 @@ grl_media_set_certificate (GrlMedia *data, const gchar *certificate)
 /**
  * grl_media_set_license:
  * @data: the media
- * @certificate: The license of the media
+ * @license: The license of the media
  *
  * Set the media license
  */
diff --git a/src/grl-metadata-source.c b/src/grl-metadata-source.c
index ce7d6e1..a54bf4c 100644
--- a/src/grl-metadata-source.c
+++ b/src/grl-metadata-source.c
@@ -1109,6 +1109,7 @@ grl_metadata_source_get_description (GrlMetadataSource *source)
  * @media: the #GrlMedia object that we want to operate on.
  * @keys: (element-type GObject.ParamSpec) (transfer none) (allow-none): a list
  * of #GrlKeyID whose values we want to change.
+ * @flags: Flags to configure specific behaviors of the operation.
  * @callback: (scope notified): the callback to execute when the operation is finished.
  * @user_data: user data set for the @callback
  *
@@ -1171,9 +1172,8 @@ grl_metadata_source_set_metadata (GrlMetadataSource *source,
  * @media: the #GrlMedia object that we want to operate on
  * @keys: (element-type GObject.ParamSpec) (allow-none) (transfer none): a list of
  * #GrlKeyID whose values we want to change
+ * @flags: Flags to configure specific behaviors of the operation.
  * @error: a #GError, or @NULL
- * @callback: the callback to execute when the operation is finished
- * @user_data: user data set for the @callback
  *
  * This is the main method of the #GrlMetadataSource class. It will
  * get the value for @key from @media and store it permanently. After
diff --git a/src/grl-metadata-source.h b/src/grl-metadata-source.h
index 9694d5a..e225e28 100644
--- a/src/grl-metadata-source.h
+++ b/src/grl-metadata-source.h
@@ -164,11 +164,11 @@ typedef struct {
  * GrlMetadataSourceSetMetadataSpec:
  * @source: a metadata source
  * @media: a #GrlMedia transfer object
- * @key_id: Key which value is to be stored
+ * @keys: List of keys to be stored/updated.
+ * @flags: Flags to control specific bahviors of the set metadata operation.
  * @callback: the callback passed to grl_metadata_source_set_metadata()
  * @user_data: user data passed to grl_metadata_source_set_metadata()
  * @failed_keys: for internal use of the framework only.
- * @keymaps: for internal use of the framework only.
  *
  * Represents the closure used by the derived objects to operate.
  */
@@ -184,15 +184,16 @@ typedef struct {
 
 /**
  * GrlSupportedOps:
- * @GRL_OP_NONE: no one operation is supported
- * @GRL_OP_METADATA: TBD
- * @GRL_OP_RESOLVE: Fetch specific keys of metadata
+ * @GRL_OP_NONE: no operation is supported
+ * @GRL_OP_METADATA: Fetch specific keys of metadata based on the media id.
+ * @GRL_OP_RESOLVE: Fetch specific keys of metadata based on other metadata.
  * @GRL_OP_BROWSE: Retrieve complete sets of #GrlMedia
- * @GRL_OP_SEARCH: Look up for #GrlMedia given a query
- * @GRL_OP_QUERY: TBD
- * @GRL_OP_STORE: TBD
- * @GRL_OP_STORE_PARENT: TBD
- * @GRL_OP_REMOVE: TBD
+ * @GRL_OP_SEARCH: Look up for #GrlMedia given a search text
+ * @GRL_OP_QUERY:  Look up for #GrlMedia give a service specific query
+ * @GRL_OP_STORE: Store content in a service
+ * @GRL_OP_STORE_PARENT: Store content as child of a certian parent category.
+ * @GRL_OP_REMOVE: Remove content from a service.
+ * @GRL_OP_SET_METADATA: Update metadata of a #GrlMedia in a service.
  *
  * Bitwise flags which reflect the kind of operations that a
  * #GrlMediaPlugin supports.
diff --git a/src/grl-multiple.c b/src/grl-multiple.c
index e32ed35..b8f4136 100644
--- a/src/grl-multiple.c
+++ b/src/grl-multiple.c
@@ -515,7 +515,7 @@ grl_multiple_search (const GList *sources,
 
 /**
  * grl_multiple_cancel:
- * @operation_id: the identifier of the multiple operation to cancel
+ * @search_id: the identifier of the multiple operation to cancel
  *
  * Cancel a running multiple search by issuing a cancel operation on each
  * source involved involved in the operation.
diff --git a/src/grl-plugin-registry.h b/src/grl-plugin-registry.h
index a293b49..49d7a00 100644
--- a/src/grl-plugin-registry.h
+++ b/src/grl-plugin-registry.h
@@ -98,6 +98,7 @@ typedef struct _GrlPluginInfo GrlPluginInfo;
  * GrlPluginInfo:
  * @id: the module identifier
  * @filename: the filename containing the plugin
+ * @optional_info: Key/value pairs with extra information about the plugin.
  * @rank: the plugin priority rank
  *
  * This structure stores the information related to a module