[geocode-glib/bilelmoussaoui/gi-docgen: 4/9] docs: re-organise things a bit

[Bilal Elmoussaoui <bilelmoussaoui src gnome org>]

commit f7eaa9ce11f461ce750c5f36fa5524b40e3d3672
Author: Bilal Elmoussaoui <bil elmoussaoui gmail com>
Date:   Fri Jan 14 13:22:26 2022 +0100

    docs: re-organise things a bit
    
    Mostly adding missing links and make the representation
    on the end-result looks nicer

 geocode-glib/geocode-backend.c      | 16 ++++++++++------
 geocode-glib/geocode-bounding-box.c |  3 +--
 geocode-glib/geocode-forward.c      |  4 +++-
 geocode-glib/geocode-nominatim.c    | 23 ++++++++++++++---------
 geocode-glib/geocode-place.c        |  7 ++++---
 geocode-glib/geocode-reverse.c      |  8 ++++++--
 6 files changed, 38 insertions(+), 23 deletions(-)
---
diff --git a/geocode-glib/geocode-backend.c b/geocode-glib/geocode-backend.c
index dba1dd3..0c3f235 100644
--- a/geocode-glib/geocode-backend.c
+++ b/geocode-glib/geocode-backend.c
@@ -44,7 +44,7 @@
  * 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.
+ * implementing the synchronous [vfunc@Backend.forward_search] and [vfunc@Backend.reverse_resolve] methods.
  * The asynchronous versions may be implemented as well; the default
  * implementations run the synchronous version in a thread.
  *
@@ -75,8 +75,9 @@ G_DEFINE_INTERFACE (GeocodeBackend, geocode_backend, G_TYPE_OBJECT)
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
  * @user_data: the data to pass to the @callback function
  *
- * Asynchronously performs a forward geocoding query using the @backend. Use
- * [method@Backend.forward_search] to do the same thing synchronously.
+ * Asynchronously performs a forward geocoding query using the @backend. 
+ * 
+ * Use [method@Backend.forward_search] to do the same thing synchronously.
  *
  * The @params hash table is in the format used by Telepathy, and documented
  * in the [Telepathy 
specification](http://telepathy.freedesktop.org/spec/Connection_Interface_Location.html#Mapping:Location).
@@ -112,8 +113,9 @@ geocode_backend_forward_search_async (GeocodeBackend      *backend,
  * @result: a #GAsyncResult.
  * @error: a #GError.
  *
- * Finishes a forward geocoding operation. See
- * [method@Backend.forward_search_async].
+ * Finishes a forward geocoding operation. 
+ * 
+ * See [method@Backend.forward_search_async].
  *
  * Returns: (element-type GeocodePlace) (transfer full): A list of
  * places or %NULL in case of errors. Free the returned instances with
@@ -229,7 +231,9 @@ geocode_backend_reverse_resolve_async (GeocodeBackend      *backend,
  * @result: a #GAsyncResult.
  * @error: a #GError.
  *
- * Finishes a reverse geocoding operation. See [method@Backend.reverse_resolve_async].
+ * Finishes a reverse geocoding operation. 
+ * 
+ * See [method@Backend.reverse_resolve_async].
  *
  * Returns: (transfer full) (element-type GeocodePlace): A list of
  *    #GeocodePlace instances, or %NULL in case of errors. The list is ordered
diff --git a/geocode-glib/geocode-bounding-box.c b/geocode-glib/geocode-bounding-box.c
index 83f6656..98a9d93 100644
--- a/geocode-glib/geocode-bounding-box.c
+++ b/geocode-glib/geocode-bounding-box.c
@@ -25,8 +25,7 @@
 /**
  * GeocodeBoundingBox:
  *
- * The #GeocodeBoundingBox represents a geographical area on earth, bounded
- * by top, bottom, left and right coordinates.
+ * Represents a geographical area on earth, bounded by top, bottom, left and right coordinates.
  **/
 
 struct _GeocodeBoundingBoxPrivate {
diff --git a/geocode-glib/geocode-forward.c b/geocode-glib/geocode-forward.c
index d430665..d96b9cf 100644
--- a/geocode-glib/geocode-forward.c
+++ b/geocode-glib/geocode-forward.c
@@ -346,7 +346,9 @@ geocode_forward_search_async (GeocodeForward      *forward,
  * @res: a #GAsyncResult.
  * @error: a #GError.
  *
- * Finishes a forward geocoding operation. See [method@Forward.search_async].
+ * Finishes a forward geocoding operation. 
+ * 
+ * See [method@Forward.search_async].
  *
  * Returns: (element-type GeocodePlace) (transfer full): A list of
  * places or %NULL in case of errors. Free the returned instances with
diff --git a/geocode-glib/geocode-nominatim.c b/geocode-glib/geocode-nominatim.c
index ad95e35..c687c33 100644
--- a/geocode-glib/geocode-nominatim.c
+++ b/geocode-glib/geocode-nominatim.c
@@ -37,9 +37,10 @@
  *
  * Contains functions for geocoding using the
  * [OSM Nominatim APIs](http://wiki.openstreetmap.org/wiki/Nominatim) exposed
- * by a Nominatim server at a given URI. By default, the GNOME Nominatim server
- * is used, but other server details may be given when constructing a
- * #GeocodeNominatim.
+ * by a Nominatim server at a given URI. 
+ * 
+ * By default, the GNOME Nominatim server is used, but other server details may be given 
+ * when constructing a #GeocodeNominatim.
  *
  * Since: 3.23.1
  */
@@ -1376,7 +1377,7 @@ static GWeakRef backend_nominatim_gnome;
 /**
  * geocode_nominatim_get_gnome:
  *
- * Gets a reference to the default Nominatim server on <nominatim.gnome.org>.
+ * Gets a reference to the default Nominatim server on <https://nominatim.gnome.org>.
  *
  * This function is thread-safe.
  *
@@ -1408,8 +1409,9 @@ geocode_nominatim_get_gnome (void)
  * @base_url: a the base URL of the Nominatim server.
  * @maintainer_email_address: the email address of the software maintainer.
  *
- * Creates a new backend implementation for an online Nominatim server. See
- * the documentation for [property@Nominatim:base-url] and
+ * Creates a new backend implementation for an online Nominatim server. 
+ * 
+ * See the documentation for [property@Nominatim:base-url] and
  * [property@Nominatim:maintainer-email-address].
  *
  * Returns: (transfer full): a new #GeocodeNominatim. Use g_object_unref() when done.
@@ -1572,8 +1574,9 @@ geocode_nominatim_class_init (GeocodeNominatimClass *klass)
         * GeocodeNominatim:maintainer-email-address:
         *
         * E-mail address of the maintainer of the software making the
-        * geocoding requests to the  Nominatim server. This is used to contact
-        * them in the event of a problem with their usage. See
+        * geocoding requests to the  Nominatim server. 
+        * 
+        * This is used to contact them in the event of a problem with their usage. See
         * [the Nominatim API](http://wiki.openstreetmap.org/wiki/Nominatim).
         *
         * Since: 3.23.1
@@ -1591,7 +1594,9 @@ geocode_nominatim_class_init (GeocodeNominatimClass *klass)
         * GeocodeNominatim:user-agent:
         *
         * User-Agent string to send with HTTP(S) requests, or %NULL to use the
-        * default user agent, which is derived from the geocode-glib version
+        * default user agent.
+        * 
+        * The default user agent is derived from the geocode-glib version
         * and [property@Gio.Application:application_id], for example: `geocode-glib/3.20 (MyAppId)`.
         *
         * As per the
diff --git a/geocode-glib/geocode-place.c b/geocode-glib/geocode-place.c
index 66c1963..dc2ca28 100644
--- a/geocode-glib/geocode-place.c
+++ b/geocode-glib/geocode-place.c
@@ -30,8 +30,9 @@
 /**
  * GeocodePlace:
  *
- * The #GeocodePlace instance represents a place on earth. While
- * [class@Location] represents a point on the planet, #GeocodePlace represents
+ * Represents a place on earth. 
+ * 
+ * While [class@Location] represents a point on the planet, #GeocodePlace represents
  * places, e.g street, town, village, county, country or points of interest
  * (POI) etc.
  **/
@@ -1266,7 +1267,7 @@ geocode_place_get_bounding_box (GeocodePlace *place)
  * @place: A place
  * @bbox: A #GeocodeBoundingBox for the place
  *
- * Sets the #GeocodeBoundingBox for the place @place.
+ * Sets the [class@BoundingBox] for the place @place.
  *
  **/
 void
diff --git a/geocode-glib/geocode-reverse.c b/geocode-glib/geocode-reverse.c
index a423294..8afa078 100644
--- a/geocode-glib/geocode-reverse.c
+++ b/geocode-glib/geocode-reverse.c
@@ -81,6 +81,7 @@ geocode_reverse_init (GeocodeReverse *object)
  * @location: a #GeocodeLocation object
  *
  * Creates a new #GeocodeReverse to perform reverse geocoding with.
+ * 
  * Use [method@Reverse.resolve_async] to perform the resolution.
  *
  * Returns: a new #GeocodeReverse. Use g_object_unref() when done.
@@ -213,7 +214,9 @@ geocode_reverse_resolve_async (GeocodeReverse     *object,
  * @res: a #GAsyncResult.
  * @error: a #GError.
  *
- * Finishes a reverse geocoding operation. See [method@Reverse.resolve_async].
+ * Finishes a reverse geocoding operation. 
+ * 
+ * See [method@Reverse.resolve_async].
  *
  * Returns: (transfer full): A #GeocodePlace instance, or %NULL in case of
  * errors. Free the returned instance with #g_object_unref() when done.
@@ -236,7 +239,8 @@ geocode_reverse_resolve_finish (GeocodeReverse *object,
  * @error: a #GError
  *
  * Gets the result of a reverse geocoding query using the current backend 
- * (see [method@Reverse.set_backend]). 
+ * 
+ * See [method@Reverse.set_backend] to modify the used backend. 
  * 
  * By default the GNOME Nominatim server is used. See [iface@Backend] for more
  * information.