[geocode-glib] docs: Clarify error returns from GeocodeBackend

[Philip Withnall <pwithnall src gnome org>]

commit 7ec672c613d9c6f757732ceabb621ef340372f5a
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Wed Nov 16 17:08:46 2016 +0000

    docs: Clarify error returns from GeocodeBackend
    
    These are a bit inconsistent, especially in the case of returning no
    results (which I would expect to return an empty result list, rather
    than an error), but are what the Nominatim code has always done, so we
    have to keep that API for backwards compatibility.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=774631

 geocode-glib/geocode-backend.c |    6 ++++++
 geocode-glib/geocode-forward.c |    2 ++
 geocode-glib/geocode-reverse.c |    4 ++++
 3 files changed, 12 insertions(+), 0 deletions(-)
---
diff --git a/geocode-glib/geocode-backend.c b/geocode-glib/geocode-backend.c
index 5ab58c4..add0614 100644
--- a/geocode-glib/geocode-backend.c
+++ b/geocode-glib/geocode-backend.c
@@ -115,6 +115,8 @@ geocode_backend_forward_search_finish (GeocodeBackend  *backend,
  *
  * Gets the result of a forward geocoding query using the @backend.
  *
+ * If no results are found, a %GEOCODE_ERROR_NO_MATCHES error is returned.
+ *
  * This is a synchronous function, which means it may block on network requests.
  * In most situations, the asynchronous version
  * (geocode_backend_forward_search_async()) is more appropriate. See its
@@ -230,6 +232,10 @@ geocode_backend_reverse_resolve_finish (GeocodeBackend  *backend,
  *
  * Gets the result of a reverse geocoding query using the @backend.
  *
+ * 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
+ * middle of the ocean.
+ *
  * This is a synchronous function, which means it may block on network requests.
  * In most situations, the asynchronous version,
  * geocode_backend_forward_search_async(), is more appropriate. See its
diff --git a/geocode-glib/geocode-forward.c b/geocode-glib/geocode-forward.c
index 057485e..f55aa20 100644
--- a/geocode-glib/geocode-forward.c
+++ b/geocode-glib/geocode-forward.c
@@ -374,6 +374,8 @@ geocode_forward_search_finish (GeocodeForward       *forward,
  * Gets the result of a forward geocoding
  * query using a web service.
  *
+ * If no results are found, a %GEOCODE_ERROR_NO_MATCHES error is returned.
+ *
  * Returns: (element-type GeocodePlace) (transfer full): A list of
  * places or %NULL in case of errors. Free the returned instances with
  * g_object_unref() and the list with g_list_free() when done.
diff --git a/geocode-glib/geocode-reverse.c b/geocode-glib/geocode-reverse.c
index 0323cbb..27455d7 100644
--- a/geocode-glib/geocode-reverse.c
+++ b/geocode-glib/geocode-reverse.c
@@ -247,6 +247,10 @@ geocode_reverse_resolve_finish (GeocodeReverse *object,
  * Gets the result of a reverse geocoding
  * query using a web service.
  *
+ * 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
+ * middle of the ocean.
+ *
  * Returns: (transfer full): A #GeocodePlace instance, or %NULL in case of
  * errors. Free the returned instance with #g_object_unref() when done.
  **/