[geocode-glib/bilelmoussaoui/gi-docgen: 2/8] docs: port the documentations to gi-docgen annotations

From: Bilal Elmoussaoui <bilelmoussaoui src gnome org>
To: commits-list gnome org
Cc:
Subject: [geocode-glib/bilelmoussaoui/gi-docgen: 2/8] docs: port the documentations to gi-docgen annotations
Date: Fri, 14 Jan 2022 12:46:28 +0000 (UTC)

commit a7a860885b90c0084e30483254eeb20492ac8c35
Author: Bilal Elmoussaoui <bil elmoussaoui gmail com>
Date:   Fri Jan 14 13:02:27 2022 +0100

    docs: port the documentations to gi-docgen annotations

 geocode-glib/geocode-backend.c      | 34 +++++++++++-----------
 geocode-glib/geocode-bounding-box.c |  4 +--
 geocode-glib/geocode-forward.c      | 30 ++++++++++----------
 geocode-glib/geocode-location.c     | 37 +++++++++++-------------
 geocode-glib/geocode-mock-backend.c | 56 +++++++++++++++++++------------------
 geocode-glib/geocode-nominatim.c    | 14 ++++------
 geocode-glib/geocode-place.c        | 19 ++++++-------
 geocode-glib/geocode-reverse.c      | 25 ++++++++---------
 8 files changed, 104 insertions(+), 115 deletions(-)
---
diff --git a/geocode-glib/geocode-backend.c b/geocode-glib/geocode-backend.c
index 4ee310f..dba1dd3 100644
--- a/geocode-glib/geocode-backend.c
+++ b/geocode-glib/geocode-backend.c
@@ -24,19 +24,17 @@
 #include "geocode-backend.h"
 
 /**
- * SECTION:geocode-backend
- * @short_description: Geocode backend object
- * @include: geocode-glib/geocode-glib.h
+ * GeocodeBackend:
  *
  * 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
+ * geocoding database and functionality. By default, the [class@Nominatim]
  * 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
+ * Otherwise, you should use a new [class@Nominatim] 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.
@@ -52,17 +50,17 @@
  *
  * 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
+ * or create [class@Forward] and [class@Reverse] objects as normal, and set
+ * the backend they use with [method@Forward.set_backend] and
+ * [method@Reverse.set_backend]. They default to using the GNOME Nominatim
  * backend.
  *
- * #GeocodeMockBackend is intended to be used in unit tests for applications
+ * [class@MockBackend] 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.
+ * It is not expected that [class@MockBackend] will be used in production code.
  *
  * Since: 3.23.1
  */
@@ -78,7 +76,7 @@ G_DEFINE_INTERFACE (GeocodeBackend, geocode_backend, G_TYPE_OBJECT)
  * @user_data: the data to pass to the @callback function
  *
  * Asynchronously performs a forward geocoding query using the @backend. Use
- * geocode_backend_forward_search() to do the same thing synchronously.
+ * [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).
@@ -86,7 +84,7 @@ G_DEFINE_INTERFACE (GeocodeBackend, geocode_backend, G_TYPE_OBJECT)
  * See also: [XEP-0080 specification](http://xmpp.org/extensions/xep-0080.html).
  *
  * When the operation is finished, @callback will be called. You can then call
- * geocode_backend_forward_search_finish() to get the result of the operation.
+ * [method@Backend.forward_search_finish] to get the result of the operation.
  *
  * Since: 3.23.1
  */
@@ -115,7 +113,7 @@ geocode_backend_forward_search_async (GeocodeBackend      *backend,
  * @error: a #GError.
  *
  * Finishes a forward geocoding operation. See
- * geocode_backend_forward_search_async().
+ * [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
@@ -152,7 +150,7 @@ geocode_backend_forward_search_finish (GeocodeBackend  *backend,
  *
  * 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
+ * ([method@Backend.forward_search_async]) is more appropriate. See its
  * documentation for more information on usage.
  *
  * Returns: (element-type GeocodePlace) (transfer full): A list of
@@ -199,10 +197,10 @@ geocode_backend_forward_search (GeocodeBackend  *backend,
  *
  * See also: [XEP-0080 specification](http://xmpp.org/extensions/xep-0080.html).
  *
- * Use geocode_backend_reverse_resolve() to do the same thing synchronously.
+ * Use [method@Backend.reverse_resolve] to do the same thing synchronously.
  *
  * When the operation is finished, @callback will be called. You can then call
- * geocode_backend_reverse_resolve_finish() to get the result of the operation.
+ * [method@Backend.reverse_resolve_finish] to get the result of the operation.
  *
  * Since: 3.23.1
  */
@@ -231,7 +229,7 @@ geocode_backend_reverse_resolve_async (GeocodeBackend      *backend,
  * @result: a #GAsyncResult.
  * @error: a #GError.
  *
- * Finishes a reverse geocoding operation. See geocode_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
@@ -271,7 +269,7 @@ geocode_backend_reverse_resolve_finish (GeocodeBackend  *backend,
  *
  * 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
+ * [method@Backend.forward_search_async], is more appropriate. See its
  * documentation for more information on usage.
  *
  * Returns: (transfer full) (element-type GeocodePlace): A list of
diff --git a/geocode-glib/geocode-bounding-box.c b/geocode-glib/geocode-bounding-box.c
index 2dd99de..83f6656 100644
--- a/geocode-glib/geocode-bounding-box.c
+++ b/geocode-glib/geocode-bounding-box.c
@@ -23,9 +23,7 @@
 #include <geocode-glib/geocode-bounding-box.h>
 
 /**
- * SECTION:geocode-bounding-box
- * @short_description: Geocode BoundingBox object
- * @include: geocode-glib/geocode-bounding-box.h
+ * GeocodeBoundingBox:
  *
  * The #GeocodeBoundingBox represents a geographical area on earth, bounded
  * by top, bottom, left and right coordinates.
diff --git a/geocode-glib/geocode-forward.c b/geocode-glib/geocode-forward.c
index 43ea4ad..d430665 100644
--- a/geocode-glib/geocode-forward.c
+++ b/geocode-glib/geocode-forward.c
@@ -33,9 +33,7 @@
 #include <geocode-glib/geocode-nominatim.h>
 
 /**
- * SECTION:geocode-forward
- * @short_description: Geocode forward geocoding object
- * @include: geocode-glib/geocode-glib.h
+ * GeocodeForward:
  *
  * Contains functions for geocoding using the
  * <ulink url="http://wiki.openstreetmap.org/wiki/Nominatim";>OSM Nominatim APIs</ulink>
@@ -165,7 +163,7 @@ geocode_forward_class_init (GeocodeForwardClass *klass)
        * GeocodeForward:search-area:
        *
        * The bounding box that limits the search area.
-       * If #GeocodeForward:bounded property is set to #TRUE only results from
+       * If [property@Forward:bounded] property is set to #TRUE only results from
        * this area is returned.
        */
        pspec = g_param_spec_object ("search-area",
@@ -179,9 +177,9 @@ geocode_forward_class_init (GeocodeForwardClass *klass)
        /**
        * GeocodeForward:bounded:
        *
-       * If set to #TRUE then only results in the #GeocodeForward:search-area
+       * If set to #TRUE then only results in the [property@Forward:search-area]
        * bounding box are returned.
-       * If set to #FALSE the #GeocodeForward:search-area is treated like a
+       * If set to #FALSE the [property@Forward:search-area] is treated like a
        * preferred area for results.
        */
        pspec = g_param_spec_boolean ("bounded",
@@ -313,11 +311,11 @@ backend_forward_search_ready (GeocodeBackend *backend,
  * @user_data: the data to pass to callback function
  *
  * Asynchronously performs a forward geocoding
- * query using a web service. Use geocode_forward_search() to do the same
+ * query using a web service. Use [method@Forward.search] to do the same
  * thing synchronously.
  *
  * When the operation is finished, @callback will be called. You can then call
- * geocode_forward_search_finish() to get the result of the operation.
+ * [method@Forward.search_finish] to get the result of the operation.
  **/
 void
 geocode_forward_search_async (GeocodeForward      *forward,
@@ -348,7 +346,7 @@ geocode_forward_search_async (GeocodeForward      *forward,
  * @res: a #GAsyncResult.
  * @error: a #GError.
  *
- * Finishes a forward geocoding operation. See geocode_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
@@ -372,8 +370,8 @@ geocode_forward_search_finish (GeocodeForward       *forward,
  * @error: a #GError
  *
  * Gets the result of a forward geocoding
- * query using the current backend (see geocode_forward_set_backend()). By
- * default the GNOME Nominatim server is used. See #GeocodeBackend for more
+ * query using the current backend (see [method@Forward.set_backend]). By
+ * default the GNOME Nominatim server is used. See [iface@Backend] for more
  * information.
  *
  * If no results are found, a %GEOCODE_ERROR_NO_MATCHES error is returned.
@@ -474,10 +472,10 @@ geocode_forward_set_search_area (GeocodeForward     *forward,
  * geocode_forward_set_bounded:
  * @forward: a #GeocodeForward representing a query
  * @bounded: #TRUE to restrict results to only items contained within the
- * #GeocodeForward:search-area bounding box.
+ * [property@Forward:search-area] bounding box.
  *
- * Set the #GeocodeForward:bounded property that regulates whether the
- * #GeocodeForward:search-area property acts restricting or not.
+ * Set the [property@Forward:bounded] property that regulates whether the
+ * [property@Forward:search-area] property acts restricting or not.
  **/
 void
 geocode_forward_set_bounded (GeocodeForward *forward,
@@ -532,8 +530,8 @@ geocode_forward_get_search_area (GeocodeForward *forward)
  * geocode_forward_get_bounded:
  * @forward: a #GeocodeForward representing a query
  *
- * Gets the #GeocodeForward:bounded property that regulates whether the
- * #GeocodeForward:search-area property acts restricting or not.
+ * Gets the [property@Forward:bounded] property that regulates whether the
+ * [property@Forward:search-area] property acts restricting or not.
  **/
 gboolean
 geocode_forward_get_bounded (GeocodeForward *forward)
diff --git a/geocode-glib/geocode-location.c b/geocode-glib/geocode-location.c
index 70a94c1..6e507c6 100644
--- a/geocode-glib/geocode-location.c
+++ b/geocode-glib/geocode-location.c
@@ -30,12 +30,9 @@
 #define EARTH_RADIUS_KM 6372.795
 
 /**
- * SECTION:geocode-location
- * @short_description: Geocode location object
- * @include: geocode-glib/geocode-glib.h
+ * GeocodeLocation:
  *
- * The #GeocodeLocation instance represents a location on earth, with an
- * optional description.
+ * Represents a location on earth, with an optional description.
  **/
 
 struct _GeocodeLocationPrivate {
@@ -118,16 +115,17 @@ geocode_location_get_property (GObject    *object,
  * @a: a location
  * @b: another location
  *
- * Compare two #GeocodeLocation instances for equality. This compares all fields
- * and only returns %TRUE if the instances are exactly equal. For example, if
- * both locations have the same physical coordinates, but one location has its
- * #GeocodeLocation:description property set and the other does not, %FALSE
+ * Compare two #GeocodeLocation instances for equality. 
+ * 
+ * This compares all fields and only returns %TRUE if the instances are exactly equal. 
+ * For example, if both locations have the same physical coordinates, but one location has its
+ * [property@Location:description] property set and the other does not, %FALSE
  * will be returned. Similarly, if both locations have the same
- * #GeocodeLocation:latitude, #GeocodeLocation:longitude and
- * #GeocodeLocation:altitude, but a different #GeocodeLocation:accuracy or
- * #GeocodeLocation:timestamp, %FALSE will be returned. Or if both locations
- * have the same#GeocodeLocation:latitude and #GeocodeLocation:longitude but a
- * different #GeocodeLocation:altitude, %FALSE will be returned.
+ * [property@Location:latitude], [property@Location:longitude] and
+ * [property@Location:altitude], but a different [property@Location:accuracy] or
+ * [property@Location:timestamp], %FALSE will be returned. Or if both locations
+ * have the same[property@Location:latitude] and [property@Location:longitude] but a
+ * different [property@Location:altitude], %FALSE will be returned.
  *
  * Both instances must be non-%NULL.
  *
@@ -727,13 +725,12 @@ geocode_location_new_with_description (gdouble     latitude,
  * The URI should be in the geo scheme (RFC 5870) which in its simplest form
  * looks like:
  *
- * - geo:latitude,longitude
+ * - `geo:latitude,longitude`
  *
- * An <ulink
- * url="http://developer.android.com/guide/components/intents-common.html#Maps";>
- * Android extension</ulink> to set a description is also supported in the form of:
+ * An [Android extension](http://developer.android.com/guide/components/intents-common.html#Maps) 
+ * to set a description is also supported in the form of:
  *
- * - geo:0,0?q=latitude,longitude(description)
+ * - `geo:0,0?q=latitude,longitude(description)`
  *
  * Returns: %TRUE on success and %FALSE on error.
  **/
@@ -866,7 +863,7 @@ geocode_location_get_crs (GeocodeLocation *loc)
  * @loc: a #GeocodeLocation
  *
  * Gets the timestamp (in seconds since the Epoch) of location @loc. See
- * #GeocodeLocation:timestamp.
+ * [property@Location:timestamp].
  *
  * Returns: The timestamp of location @loc.
  **/
diff --git a/geocode-glib/geocode-mock-backend.c b/geocode-glib/geocode-mock-backend.c
index a232ff9..85d3b08 100644
--- a/geocode-glib/geocode-mock-backend.c
+++ b/geocode-glib/geocode-mock-backend.c
@@ -30,12 +30,12 @@
 #include "geocode-mock-backend.h"
 
 /**
- * SECTION:geocode-mock-backend
- * @short_description: Geocode mock backend implementation
- * @include: geocode-glib/geocode-glib.h
+ * GeocodeMockBackend:
  *
  * #GeocodeMockBackend is intended to be used in unit tests for applications
- * which use geocode-glib — it allows them to set the geocode results they
+ * 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. It works offline, which allows application unit tests to be
  * run on integration and build machines which are not online. It is not
@@ -43,13 +43,13 @@
  *
  * To use it, create the backend instance, add the query results to it which
  * you want to be returned to your application’s queries, then use it as the
- * #GeocodeBackend for geocode_forward_set_backend() or
- * geocode_reverse_set_backend(). After a test has been run, the set of queries
+ * [iface@Backend] for [method@Forward.set_backend] or
+ * [method@Reverse.set_backend]. After a test has been run, the set of queries
  * which the code under test actually made on the backend can be checked using
- * geocode_mock_backend_get_query_log(). The backend can be reset using
- * geocode_mock_backend_clear() and new queries added for the next test.
+ * [method@MockBackend.get_query_log]. The backend can be reset using
+ * [method@MockBackend.clear] and new queries added for the next test.
  *
- * |[<!-- language="C" -->
+ * ```c
  * static void
  * place_list_free (GList *l)
  * {
@@ -72,15 +72,15 @@
  *
  * backend = geocode_mock_backend_new ();
  *
- * /<!-- -->* Build the set of parameters the mock backend expects to receive from
- *  * the #GeocodeForward instance. *<!-- -->/
+ * // Build the set of parameters the mock backend expects to receive from
+ * // the #GeocodeForward instance.
  * params = g_hash_table_new_full (g_str_hash, g_str_equal, NULL, NULL);
  *
  * g_value_init (&location, G_TYPE_STRING);
  * g_value_set_static_string (&location, "Bullpot Farm");
  * g_hash_table_insert (params, (gpointer) "location", &location);
  *
- * /<!-- -->* Build the set of results the mock backend should return. *<!-- -->/
+ * // Build the set of results the mock backend should return.
  * expected_location = geocode_location_new_with_description (
  *     54.22759825, -2.51857179181113, 5.0,
  *     "Bullpot Farm, Fell Road, South Lakeland, Cumbria, "
@@ -93,8 +93,8 @@
  * geocode_mock_backend_add_forward_result (backend, params,
  *                                          expected_results, NULL);
  *
- * /<!-- -->* Do the search. This would typically call the application code
- *  * under test, rather than geocode-glib directly. *<!-- -->/
+ * // Do the search. This would typically call the application code
+ * // under test, rather than geocode-glib directly.
  * forward = geocode_forward_new_for_string ("Bullpot Farm");
  * geocode_forward_set_backend (forward, GEOCODE_BACKEND (backend));
  * results = geocode_forward_search (forward, &error);
@@ -102,10 +102,10 @@
  * g_assert_no_error (error);
  * assert_place_list_equal (results, expected_results);
  *
- * /<!-- -->* Check the application made the expected query. *<!-- -->/
+ * // Check the application made the expected query.
  * query_log = geocode_mock_backend_get_query_log (backend);
  * g_assert_cmpuint (query_log->len, ==, 1);
- * ]|
+ * ```
  *
  * Since: 3.23.1
  */
@@ -427,7 +427,7 @@ geocode_mock_backend_new (void)
  *
  * Add a query and corresponding result (or error) to the mock backend, meaning
  * that if it receives a forward search for @params through
- * geocode_backend_forward_search() (or its asynchronous variants), the mock
+ * [method@Backend.forward_search] (or its asynchronous variants), the mock
  * backend will return the given @results or @error to the caller.
  *
  * If a set of @params is added to the backend multiple times, the most
@@ -472,7 +472,7 @@ geocode_mock_backend_add_forward_result (GeocodeMockBackend *self,
  *
  * Add a query and corresponding result (or error) to the mock backend, meaning
  * that if it receives a reverse search for @params through
- * geocode_backend_reverse_resolve() (or its asynchronous variants), the mock
+ * [method@Backend.reverse_resolve] (or its asynchronous variants), the mock
  * backend will return the given @results or @error to the caller.
  *
  * If a set of @params is added to the backend multiple times, the most
@@ -507,10 +507,12 @@ geocode_mock_backend_add_reverse_result (GeocodeMockBackend *self,
  * geocode_mock_backend_clear:
  * @self: a #GeocodeMockBackend
  *
- * Clear the set of stored results in the mock backend which have been added
- * using geocode_mock_backend_add_forward_result() and
- * geocode_mock_backend_add_reverse_result(). Additionally, clear the query log
- * so far (see geocode_mock_backend_get_query_log()).
+ * Clear the set of stored results in the mock backend.
+ * 
+ * The stored results would have been added
+ * using [method@MockBackend.add_forward_result] and
+ * [method@MockBackend.add_reverse_result]. Additionally, clear the query log
+ * so far (see [method@MockBackend.get_query_log]).
  *
  * This effectively resets the mock backend to its initial state.
  *
@@ -532,14 +534,14 @@ geocode_mock_backend_clear (GeocodeMockBackend *self)
  *
  * Get the details of the forward and reverse queries which have been requested
  * of the mock backend since the most recent call to
- * geocode_mock_backend_clear(). The query details are provided as
- * #GeocodeMockBackendQuery structures, which map the query parameters to
- * either the result set or the error which geocode_backend_forward_search()
- * or geocode_backend_reverse_resolve() (or their asynchronous variants)
+ * [method@MockBackend.clear]. The query details are provided as
+ * [struct@MockBackendQuery] structures, which map the query parameters to
+ * either the result set or the error which [method@Backend.forward_search]
+ * or [method@Backend.reverse_resolve] (or their asynchronous variants)
  * returned to the caller.
  *
  * The results are provided in the order in which calls were made to
- * geocode_backend_forward_search() and geocode_backend_reverse_resolve().
+ * [method@Backend.forward_search] and [method@Backend.reverse_resolve].
  * Results for forward and reverse queries may be interleaved.
  *
  * Returns: (transfer none) (element-type GeocodeMockBackendQuery): potentially
diff --git a/geocode-glib/geocode-nominatim.c b/geocode-glib/geocode-nominatim.c
index 344610e..ad95e35 100644
--- a/geocode-glib/geocode-nominatim.c
+++ b/geocode-glib/geocode-nominatim.c
@@ -33,9 +33,7 @@
 #include "geocode-nominatim.h"
 
 /**
- * SECTION:geocode-nominatim
- * @short_description: Geocoding resolver using a Nominatim web service
- * @include: geocode-glib/geocode-glib.h
+ * GeocodeNominatim:
  *
  * Contains functions for geocoding using the
  * [OSM Nominatim APIs](http://wiki.openstreetmap.org/wiki/Nominatim) exposed
@@ -1378,7 +1376,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 <nominatim.gnome.org>.
  *
  * This function is thread-safe.
  *
@@ -1411,8 +1409,8 @@ geocode_nominatim_get_gnome (void)
  * @maintainer_email_address: the email address of the software maintainer.
  *
  * Creates a new backend implementation for an online Nominatim server. See
- * the documentation for #GeocodeNominatim:base-url and
- * #GeocodeNominatim:maintainer-email-address.
+ * 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.
  *
@@ -1558,7 +1556,7 @@ geocode_nominatim_class_init (GeocodeNominatimClass *klass)
         * GeocodeNominatim:base-url:
         *
         * The base URL of the Nominatim service, for example
-        * `https://nominatim.example.org`.
+        * <https://nominatim.example.org>.
         *
         * Since: 3.23.1
         */
@@ -1594,7 +1592,7 @@ geocode_nominatim_class_init (GeocodeNominatimClass *klass)
         *
         * 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
-        * and #GApplication:id, for example: `geocode-glib/3.20 (MyAppId)`.
+        * and [property@Gio.Application:application_id], for example: `geocode-glib/3.20 (MyAppId)`.
         *
         * As per the
         * [Nominatim usage policy](http://wiki.openstreetmap.org/wiki/Nominatim_usage_policy),
diff --git a/geocode-glib/geocode-place.c b/geocode-glib/geocode-place.c
index 1d4760c..66c1963 100644
--- a/geocode-glib/geocode-place.c
+++ b/geocode-glib/geocode-place.c
@@ -28,12 +28,10 @@
 #include <geocode-glib/geocode-glib-private.h>
 
 /**
- * SECTION:geocode-place
- * @short_description: Geocode place object
- * @include: geocode-glib/geocode-glib.h
+ * GeocodePlace:
  *
  * The #GeocodePlace instance represents a place on earth. While
- * #GeocodeLocation represents a point on the planet, #GeocodePlace represents
+ * [class@Location] represents a point on the planet, #GeocodePlace represents
  * places, e.g street, town, village, county, country or points of interest
  * (POI) etc.
  **/
@@ -526,7 +524,7 @@ geocode_place_class_init (GeocodePlaceClass *klass)
         /**
          * GeocodePlace:icon:
          *
-         * #GIcon representing the @GeocodePlace.
+         * [iface Gio Icon] representing the @GeocodePlace.
          */
         pspec = g_param_spec_object ("icon",
                                      "Icon",
@@ -651,10 +649,11 @@ bbox_equal0 (GeocodeBoundingBox *a,
  * @a: a place
  * @b: another place
  *
- * Compare two #GeocodePlace instances for equality. This compares all fields
- * and only returns %TRUE if the instances are exactly equal. For example, if
- * both places have the same #GeocodePlace:location, but place @b has its
- * #GeocodePlace:continent property set and place @a does not, %FALSE will be
+ * Compare two #GeocodePlace instances for equality. 
+ * 
+ * This compares all fields and only returns %TRUE if the instances are exactly equal. 
+ * For example, if both places have the same [property@Place:location], but place @b has its
+ * [property@Place:continent] property set and place @a does not, %FALSE will be
  * returned.
  *
  * Both instances must be non-%NULL.
@@ -1229,7 +1228,7 @@ get_icon_name (GeocodePlace *place)
  * geocode_place_get_icon:
  * @place: A place
  *
- * Gets the #GIcon representing the @place.
+ * Gets the [iface Gio Icon] representing the @place.
  *
  * Returns: (transfer none): The #GIcon representing the @place.
  **/
diff --git a/geocode-glib/geocode-reverse.c b/geocode-glib/geocode-reverse.c
index 4bfe0ea..a423294 100644
--- a/geocode-glib/geocode-reverse.c
+++ b/geocode-glib/geocode-reverse.c
@@ -34,12 +34,9 @@
 #include <geocode-glib/geocode-glib-private.h>
 
 /**
- * SECTION:geocode-reverse
- * @short_description: Geocode reverse geocoding object
- * @include: geocode-glib/geocode-glib.h
+ * GeocodeReverse:
  *
- * Contains functions for reverse geocoding using the
- * <ulink url="http://wiki.openstreetmap.org/wiki/Nominatim";>OSM Nominatim APIs</ulink>
+ * Contains functions for reverse geocoding using the [OSM Nominatim 
APIs](http://wiki.openstreetmap.org/wiki/Nominatim).
  **/
 
 struct _GeocodeReversePrivate {
@@ -84,7 +81,7 @@ geocode_reverse_init (GeocodeReverse *object)
  * @location: a #GeocodeLocation object
  *
  * Creates a new #GeocodeReverse to perform reverse geocoding with.
- * Use geocode_reverse_resolve_async() to perform the resolution.
+ * Use [method@Reverse.resolve_async] to perform the resolution.
  *
  * Returns: a new #GeocodeReverse. Use g_object_unref() when done.
  **/
@@ -177,11 +174,12 @@ backend_reverse_resolve_ready (GeocodeBackend *backend,
  * @user_data: the data to pass to callback function
  *
  * Asynchronously gets the result of a reverse geocoding
- * query using a web service. Use geocode_reverse_resolve() to do the same
- * thing synchronously.
+ * query using a web service. 
+ * 
+ * Use [method@Reverse.resolve] to do the same thing synchronously.
  *
  * When the operation is finished, @callback will be called. You can then call
- * geocode_reverse_resolve_finish() to get the result of the operation.
+ * [method@Reverse.resolve_finish] to get the result of the operation.
  **/
 void
 geocode_reverse_resolve_async (GeocodeReverse     *object,
@@ -215,7 +213,7 @@ geocode_reverse_resolve_async (GeocodeReverse     *object,
  * @res: a #GAsyncResult.
  * @error: a #GError.
  *
- * Finishes a reverse geocoding operation. See geocode_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.
@@ -237,9 +235,10 @@ geocode_reverse_resolve_finish (GeocodeReverse *object,
  * @object: a #GeocodeReverse representing a query
  * @error: a #GError
  *
- * Gets the result of a reverse geocoding
- * query using the current backend (see geocode_reverse_set_backend()). By
- * default the GNOME Nominatim server is used. See #GeocodeBackend for more
+ * Gets the result of a reverse geocoding query using the current backend 
+ * (see [method@Reverse.set_backend]). 
+ * 
+ * By default the GNOME Nominatim server is used. See [iface@Backend] for more
  * information.
  *
  * If no result could be found, a %GEOCODE_ERROR_NOT_SUPPORTED error will be
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]