[grilo/0.1.x] doc: Update documentation

[Juan A. Suarez Romero <jasuarez src gnome org>]

commit 9643d1d5cab4db9bb60613789cb2d368029fc746
Author: Juan A. Suarez Romero <jasuarez igalia com>
Date:   Wed Jun 29 09:01:59 2011 +0000

    doc: Update documentation
    
    Document the new way of cancelling operations.
    
    Signed-off-by: Juan A. Suarez Romero <jasuarez igalia com>

 doc/grilo/Makefile.am                  |    1 +
 doc/grilo/grilo-docs.sgml              |    1 +
 doc/grilo/grilo-sections.txt           |    8 +++++++-
 doc/grilo/plugins-metadata-sources.xml |   19 +++++++++++--------
 4 files changed, 20 insertions(+), 9 deletions(-)
---
diff --git a/doc/grilo/Makefile.am b/doc/grilo/Makefile.am
index 868314a..7bdce54 100644
--- a/doc/grilo/Makefile.am
+++ b/doc/grilo/Makefile.am
@@ -61,6 +61,7 @@ EXTRA_HFILES=
 IGNORE_HFILES=config.h \
 	grl-media-plugin-priv.h \
 	grl-metadata-source-priv.h \
+	grl-operations-priv.h \
 	grl-sync-priv.h \
 	grl-metadata-key-priv.h \
 	grl-marshal.h \
diff --git a/doc/grilo/grilo-docs.sgml b/doc/grilo/grilo-docs.sgml
index 0ab7baf..a749862 100644
--- a/doc/grilo/grilo-docs.sgml
+++ b/doc/grilo/grilo-docs.sgml
@@ -106,6 +106,7 @@
       <xi:include href="xml/grl-log.xml"/>
       <xi:include href="xml/grl-error.xml"/>
       <xi:include href="xml/grl-definitions.xml"/>
+      <xi:include href="xml/grl-operation.xml"/>
       <xi:include href="xml/grl-util.xml"/>
     </chapter>
   </reference>
diff --git a/doc/grilo/grilo-sections.txt b/doc/grilo/grilo-sections.txt
index 900abc6..80b5ee0 100644
--- a/doc/grilo/grilo-sections.txt
+++ b/doc/grilo/grilo-sections.txt
@@ -599,11 +599,17 @@ GRL_PADDING_SMALL
 <TITLE>Multiple</TITLE>
 grl_multiple_search
 grl_multiple_search_sync
-grl_multiple_cancel
 grl_multiple_get_media_from_uri
 </SECTION>
 
 <SECTION>
+<FILE>grl-operation</FILE>
+grl_operation_cancel
+grl_operation_set_data
+grl_operation_get_data
+</SECTION>
+
+<SECTION>
 <FILE>grl-log</FILE>
 GrlLogLevel
 GRL_LOG_DOMAIN_DEFAULT
diff --git a/doc/grilo/plugins-metadata-sources.xml b/doc/grilo/plugins-metadata-sources.xml
index 53d0c04..d345927 100644
--- a/doc/grilo/plugins-metadata-sources.xml
+++ b/doc/grilo/plugins-metadata-sources.xml
@@ -336,11 +336,11 @@ grl_foo_source_set_metadata (GrlMetadataSource *source,
       Grilo provides plugin developers with API to attach arbitrary data
       to a certain operation given its identifier. These APIs are:
       <itemizedlist>
-        <listitem>grl_metadata_source_set_operation_data</listitem>
-        <listitem>grl_metadata_source_get_operation_data</listitem>
+        <listitem>grl_operation_set_data</listitem>
+        <listitem>grl_operation_get_data</listitem>
       </itemizedlist>
       See the API reference documentation for
-      <link linkend="GrlMetadataSource">GrlMetadataSource</link> for
+      <link linkend="grilo-grl-operation">grl-operation</link> for
       more details.
     </para>
 
@@ -362,9 +362,8 @@ grl_foo_source_search (GrlMediaSource *source,
 {
   ...
   gint op_handler = foo_service_search_start (ss->text, ...);
-  grl_metadata_source_set_operation_data (GRL_METADATA_SOURCE (source),
-                                          ss->operation_id,
-                                          GINT_TO_POINTER (op_handler));
+  grl_operation_set_data (ss->operation_id,
+                          GINT_TO_POINTER (op_handler));
   ...
 }
 
@@ -374,8 +373,7 @@ grl_foo_source_cancel (GrlMetadataSource *source, guint operation_id)
   gint op_handler;
   
   op_handler =
-    GPOINTER_TO_INT (grl_metadata_source_get_operation_data (source,
-                                                             operation_id));
+    GPOINTER_TO_INT (grl_operation_get_data (operation_id));
   if (op_handler > 0) {
     foo_service_search_cancel (op_handler);
   }
@@ -387,6 +385,11 @@ grl_foo_source_cancel (GrlMetadataSource *source, guint operation_id)
       Some examples of plugins implementing cancellation support are
       grl-youtube, grl-jamendo or grl-filesystem, among others.
     </para>
+
+    <para>
+      Developers must free any data stored before the operation finishes.
+    </para>
+
   </section>
 </section>