[geocode-glib] backend: Add introductory docs for GeocodeBackend

[Philip Withnall <pwithnall src gnome org>]

commit 7b1621652eabc87cae7a01077d5623772ee1c0f5
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Thu Nov 17 16:55:30 2016 +0000

    backend: Add introductory docs for GeocodeBackend
    
    Add a longer introduction section explaining why backends exist, and
    what backends do exist.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=774631

 geocode-glib/geocode-backend.c |   33 +++++++++++++++++++++++++++++++++
 geocode-glib/geocode-forward.c |    4 +++-
 geocode-glib/geocode-reverse.c |    4 +++-
 3 files changed, 39 insertions(+), 2 deletions(-)
---
diff --git a/geocode-glib/geocode-backend.c b/geocode-glib/geocode-backend.c
index add0614..60ce016 100644
--- a/geocode-glib/geocode-backend.c
+++ b/geocode-glib/geocode-backend.c
@@ -31,6 +31,39 @@
  * The #GeocodeBackend interface defines the operations that a resolver
  * service must implement.
  *
+ * geocode-glib supports multiple backends which provide the underlying
+ * geocoding database and functionality. By default, the #GeocodeNominatim
+ * backend is used with
+ * [GNOME’s Nominatim server](https://nominatim.gnome.org/). If you are using
+ * geocode-glib in some GNOME software, this is the correct backend to use.
+ * Otherwise, you should use a new #GeocodeNominatim instance with your own
+ * Nominatim server, or a custom #GeocodeBackend implementation to use geocoding
+ * data from a non-Nominatim service. In all cases, please respect the terms of
+ * use of the service you are using.
+ *
+ * If you are writing a library which uses geocode-glib, consider exposing the
+ * choice of #GeocodeBackend in your library API, so that applications can make
+ * the best choice about which geocoding backend to use.
+ *
+ * Custom backends can be implemented by subclassing #GeocodeBackend and
+ * implementing the synchronous `forward_search` and `reverse_resolve` methods.
+ * The asynchronous versions may be implemented as well; the default
+ * implementations run the synchronous version in a thread.
+ *
+ * In order to use a custom backend, either instantiate the backend directly
+ * and do forward and reverse queries on it using the #GeocodeBackend interface;
+ * or create #GeocodeForward and #GeocodeReverse objects as normal, and set
+ * the backend they use with geocode_forward_set_backend() and
+ * geocode_reverse_set_backend(). They default to using the GNOME Nominatim
+ * backend.
+ *
+ * #GeocodeMockBackend is intended to be used in unit tests for applications
+ * which use geocode-glib — it allows them to set the geocode results they
+ * expect their application to query, and check afterwards that the queries
+ * were performed. Additionally, it works offline, which allows application
+ * unit tests to be run on integration and build machines which are not online.
+ * It is not expected that #GeocodeMockBackend will be used in production code.
+ *
  * Since: 3.23.1
  */
 
diff --git a/geocode-glib/geocode-forward.c b/geocode-glib/geocode-forward.c
index f55aa20..f848326 100644
--- a/geocode-glib/geocode-forward.c
+++ b/geocode-glib/geocode-forward.c
@@ -372,7 +372,9 @@ geocode_forward_search_finish (GeocodeForward       *forward,
  * @error: a #GError
  *
  * Gets the result of a forward geocoding
- * query using a web service.
+ * query using the current backend (see geocode_forward_set_backend()). By
+ * default the GNOME Nominatim server is used. See #GeocodeBackend for more
+ * information.
  *
  * If no results are found, a %GEOCODE_ERROR_NO_MATCHES error is returned.
  *
diff --git a/geocode-glib/geocode-reverse.c b/geocode-glib/geocode-reverse.c
index 857f78b..1e8f228 100644
--- a/geocode-glib/geocode-reverse.c
+++ b/geocode-glib/geocode-reverse.c
@@ -238,7 +238,9 @@ geocode_reverse_resolve_finish (GeocodeReverse *object,
  * @error: a #GError
  *
  * Gets the result of a reverse geocoding
- * query using a web service.
+ * query using the current backend (see geocode_reverse_set_backend()). By
+ * default the GNOME Nominatim server is used. See #GeocodeBackend for more
+ * information.
  *
  * If no result could be found, a %GEOCODE_ERROR_NOT_SUPPORTED error will be
  * returned. This typically happens if the coordinates to geocode are in the