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

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
parent 15ba67ce
......@@ -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
*/
......
......@@ -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.
*
......
......@@ -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
......
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