[grilo/mocking: 8/8] net: Move mocking docs into API docs

[Mathias Hasselmann <hasselmm src gnome org>]

commit 179355566820cb3d6e6860f76cce679471da1530
Author: Mathias Hasselmann <mathias openismus com>
Date:   Thu Oct 11 21:32:48 2012 +0200

    net: Move mocking docs into API docs

 doc/grilo/plugins-testing.xml |   84 +++++++++++++++++++++++++++++++++++++++++
 libs/net/grl-net-mock.c       |   39 -------------------
 2 files changed, 84 insertions(+), 39 deletions(-)
---
diff --git a/doc/grilo/plugins-testing.xml b/doc/grilo/plugins-testing.xml
index 063eeeb..217157e 100644
--- a/doc/grilo/plugins-testing.xml
+++ b/doc/grilo/plugins-testing.xml
@@ -96,4 +96,88 @@ $ export GRL_DEBUG="registry:*"
     Available metadata obtained for the selected item will be shown in the
     right pane for users to inspect.
   </para>
+
+  <section>
+    <title>Simulating Network Replies</title>
+
+    <para>
+      For for offline testing of plug-ins, especially in automated tests it is
+      useful to simulate and reply predefined network replies. Therefore Grilo
+      provides a few facilities for mocking network replies.
+    </para>
+
+    <para>
+      For configuring mock answers, a simple .ini file is used. The file is
+      split into a "default" section and one section per URL.
+    </para>
+
+    <programlisting>
+[default]
+version = 1
+ignored-parameters = field1[,field2[,...]] or "*"
+
+[http://www.example.com]
+data = content/of/response.txt
+timeout = 500
+    </programlisting>
+
+    <para>
+      The name of the configuration file is either "grl-mock-data.ini" which is
+      expected to be in the current directory or can be overridden by setting
+      the environment variable GRL_REQUEST_MOCK_FILE.
+    </para>
+
+    <para>
+      An easy way to capture the responses is to run your application with the
+      environment variable GRL_WEB_CAPTURE_DIR. GrlNetWc will then write all
+      each response into a file following the pattern "url-timestamp". If the
+      directory does not exist yet it will be created.
+    </para>
+
+    <section>
+      <title>The Default Section</title>
+
+      <para>
+        This section needs to be present in any mock reply configuration file.
+
+        <itemizedlist>
+          <listitem>
+            <varname>version</varname> needs to be "1".
+          </listitem>
+
+          <listitem>
+            <varname>ignored-parameters</varname> is a comma separated list of
+            query parameter names that can be used to map URLs to sections
+            without paying attention to query parameters listed here. So for
+            instance <code>http://www.example.com?q=test+query&amp;api_key=fake</code>
+            will also match <code>http://www.example.com</code>. Set this field
+            to "*" to ignore all query parameters.
+          </listitem>
+        </itemizedlist>
+      </para>
+    </section>
+
+    <section>
+      <title>The URL Sections</title>
+
+      <para>
+        The section title is used to map URLs to response files.
+
+        <itemizedlist>
+          <listitem>
+            <varname>data</varname> is a path to a text file containing the
+            raw response of the websserver. The path may be relative to this
+            configuration file or an absolute path.
+          </listitem>
+
+          <listitem>
+            <varname>timeout</varname> may be used to delay the response in
+            seconds. The default is to not delay at all.
+          </listitem>
+        </itemizedlist>
+
+        Skip the <varname>data</varname> field to provoke a "not found" error.
+      </para>
+    </section>
+  </section>
 </section>
diff --git a/libs/net/grl-net-mock.c b/libs/net/grl-net-mock.c
index 6b8f57c..1ea162a 100644
--- a/libs/net/grl-net-mock.c
+++ b/libs/net/grl-net-mock.c
@@ -20,45 +20,6 @@
  *
  */
 
-/*
- * Mock network answers of webservices through predefined files. Useful for
- * offline testing of plug-ins that provide sources from webservices.
- *
- * For configuring mock answers, a simple .ini file is used. The file is split
- * into a "default" section and one section per URL.
- * [default]
- * version = 1
- * ignored-parameters = field1[,field2[,...]] or "*"
- *
- * [http://www.example.com]
- * data = content/of/response.txt
- * timeout = 500
- *
- * Explanation of [default] parameters
- * version needs to be "1"
- * ignored-parameters can be used to map urls to sections without paying
- * attention to the query parameters of this names, so that for instance
- * <http://www.example.com?q=test+query&api_key=fake> will also match
- * <http://www.example.com>. Set "*" to ignore any parameter.
- *
- * Explanation of [url] sections
- * The section title is used to map urls to response files.
- * "data" is a path to a text file containing the raw response of the websserver.
- * The path may be relative to the configuration file or an absolute path.
- * "timeout" may be used to delay the response and in seconds. The default is
- * don't delay at all.
- * If you want to provoke a "not found" error, skip the "data" parameter.
- *
- * The name of the configuration file is either "grl-mock-data.ini" which is
- * expected to be in the current directory or can be overridden by setting the
- * environment variable GRL_REQUEST_MOCK_FILE.
- *
- * An easy way to capture the responses is to run your application with the
- * environment variable GRL_WEB_CAPTURE_DIR. GrlNetWc will then write all
- * each response into a file following the pattern "<url>-timestamp". If the
- * directory does not exist yet it will be created.
- */
-
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif