[PATCH 1/2] doc: Update documentation

["Juan A. Suarez Romero" <jasuarez igalia com>]

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                       |   11 +++++++----
 doc/grilo/quick-start-plugins-metadata-sources.xml |   19 +++++++++++--------
 4 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/doc/grilo/Makefile.am b/doc/grilo/Makefile.am
index d533007..74ad61e 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 60c9f59..c65c570 100644
--- a/doc/grilo/grilo-docs.sgml
+++ b/doc/grilo/grilo-docs.sgml
@@ -96,6 +96,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..e446cc9 100644
--- a/doc/grilo/grilo-sections.txt
+++ b/doc/grilo/grilo-sections.txt
@@ -37,11 +37,8 @@ grl_metadata_source_writable_keys
 grl_metadata_source_may_resolve
 grl_metadata_source_resolve
 grl_metadata_source_resolve_sync
-grl_metadata_source_set_operation_data
-grl_metadata_source_get_operation_data
 grl_metadata_source_set_metadata
 grl_metadata_source_set_metadata_sync
-grl_metadata_source_cancel
 grl_metadata_source_get_id
 grl_metadata_source_get_name
 grl_metadata_source_get_description
@@ -599,11 +596,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/quick-start-plugins-metadata-sources.xml b/doc/grilo/quick-start-plugins-metadata-sources.xml
index 53d0c04..d345927 100644
--- a/doc/grilo/quick-start-plugins-metadata-sources.xml
+++ b/doc/grilo/quick-start-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>
 
-- 
1.7.4.1