Commit 7ec672c6 authored by Philip Withnall's avatar Philip Withnall Committed by Philip Withnall
Browse files

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
parent 2a105220
......@@ -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
......
......@@ -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.
......
......@@ -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.
**/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment