GNOME.org
 

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


commit eb965a616acfc0f37c644680cd32af38a07f3a6b
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      | 24 ++++++++++++++----------
 geocode-glib/geocode-bounding-box.c |  5 ++---
 geocode-glib/geocode-forward.c      | 12 +++++++-----
 geocode-glib/geocode-location.c     |  4 ++--
 geocode-glib/geocode-mock-backend.h |  6 ++++--
 geocode-glib/geocode-nominatim.c    | 27 ++++++++++++++++-----------
 geocode-glib/geocode-place.c        | 11 ++++++-----
 geocode-glib/geocode-reverse.c      | 14 +++++++++-----
 8 files changed, 60 insertions(+), 43 deletions(-)
---
diff --git a/geocode-glib/geocode-backend.c b/geocode-glib/geocode-backend.c
index dba1dd3..05d4aa5 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,12 +113,13 @@ 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
- * g_object_unref() and the list with g_list_free() when done.
+ * [method@GObject.Object.unref] and the list with [func GLib List free] when done.
  *
  * Since: 3.23.1
  */
@@ -155,7 +157,7 @@ geocode_backend_forward_search_finish (GeocodeBackend  *backend,
  *
  * 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.
+ * [method@GObject.Object.unref] and the list with [func GLib List free] when done.
  *
  * Since: 3.23.1
  */
@@ -229,12 +231,14 @@ 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
  *    by relevance, with most relevant results first. Free the returned
- *    instances with g_object_unref() and the list with g_list_free() when done.
+ *    instances with [method@GObject.Object.unref] and the list with [func GLib List free] when done.
  *
  * Since: 3.23.1
  **/
@@ -275,7 +279,7 @@ geocode_backend_reverse_resolve_finish (GeocodeBackend  *backend,
  * Returns: (transfer full) (element-type GeocodePlace): A list of
  *    #GeocodePlace instances, or %NULL in case of errors. The list is ordered
  *    by relevance, with most relevant results first. Free the returned
- *    instances with g_object_unref() and the list with g_list_free() when done.
+ *    instances with [method@GObject.Object.unref] and the list with [func GLib List free] when done.
  *
  * Since: 3.23.1
  */
diff --git a/geocode-glib/geocode-bounding-box.c b/geocode-glib/geocode-bounding-box.c
index 83f6656..8087dd7 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 {
@@ -256,7 +255,7 @@ geocode_bounding_box_init (GeocodeBoundingBox *bbox)
  *
  * Creates a new #GeocodeBoundingBox object.
  *
- * Returns: a new #GeocodeBoundingBox object. Use g_object_unref() when done.
+ * Returns: a new #GeocodeBoundingBox object. Use [method@GObject.Object.unref] when done.
  **/
 GeocodeBoundingBox *
 geocode_bounding_box_new (gdouble top,
diff --git a/geocode-glib/geocode-forward.c b/geocode-glib/geocode-forward.c
index d430665..37e7824 100644
--- a/geocode-glib/geocode-forward.c
+++ b/geocode-glib/geocode-forward.c
@@ -228,7 +228,7 @@ ensure_backend (GeocodeForward *object)
  *
  * See also: <ulink url="http://xmpp.org/extensions/xep-0080.html";>XEP-0080 specification</ulink>.
  *
- * Returns: a new #GeocodeForward. Use g_object_unref() when done.
+ * Returns: a new #GeocodeForward. Use [method@GObject.Object.unref] when done.
  **/
 GeocodeForward *
 geocode_forward_new_for_params (GHashTable *params)
@@ -266,7 +266,7 @@ geocode_forward_new_for_params (GHashTable *params)
  * Creates a new #GeocodeForward to perform forward geocoding with. The
  * string is in free-form format.
  *
- * Returns: a new #GeocodeForward. Use g_object_unref() when done.
+ * Returns: a new #GeocodeForward. Use [method@GObject.Object.unref] when done.
  **/
 GeocodeForward *
 geocode_forward_new_for_string (const char *location)
@@ -346,11 +346,13 @@ 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
- * g_object_unref() and the list with g_list_free() when done.
+ * [method@GObject.Object.unref] and the list with [func GLib List free] when done.
  **/
 GList *
 geocode_forward_search_finish (GeocodeForward       *forward,
@@ -378,7 +380,7 @@ geocode_forward_search_finish (GeocodeForward       *forward,
  *
  * 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.
+ * [method@GObject.Object.unref] and the list with [func GLib List free] when done.
  **/
 GList *
 geocode_forward_search (GeocodeForward      *forward,
diff --git a/geocode-glib/geocode-location.c b/geocode-glib/geocode-location.c
index 6e507c6..8600aa4 100644
--- a/geocode-glib/geocode-location.c
+++ b/geocode-glib/geocode-location.c
@@ -675,7 +675,7 @@ geocode_location_init (GeocodeLocation *location)
  *
  * Creates a new #GeocodeLocation object.
  *
- * Returns: a new #GeocodeLocation object. Use g_object_unref() when done.
+ * Returns: a new #GeocodeLocation object. Use [method@GObject.Object.unref] when done.
  **/
 GeocodeLocation *
 geocode_location_new (gdouble latitude,
@@ -698,7 +698,7 @@ geocode_location_new (gdouble latitude,
  *
  * Creates a new #GeocodeLocation object.
  *
- * Returns: a new #GeocodeLocation object. Use g_object_unref() when done.
+ * Returns: a new #GeocodeLocation object. Use [method@GObject.Object.unref] when done.
  **/
 GeocodeLocation *
 geocode_location_new_with_description (gdouble     latitude,
diff --git a/geocode-glib/geocode-mock-backend.h b/geocode-glib/geocode-mock-backend.h
index 72f4715..76f1b78 100644
--- a/geocode-glib/geocode-mock-backend.h
+++ b/geocode-glib/geocode-mock-backend.h
@@ -65,8 +65,10 @@ void geocode_mock_backend_clear              (GeocodeMockBackend *self);
  *     was returned
  *
  * The details of a forward or reverse query which was performed on a
- * [class@MockBackend] by application code. This includes the input (@params,
- * @is_forward), and the output which was returned (@results or @error).
+ * [class@MockBackend] by application code. 
+ * 
+ * This includes the input (@params, @is_forward), and the output which 
+ * was returned (@results or @error).
  *
  * Empty result sets are represented by the %GEOCODE_ERROR_NO_MATCHES error
  * (for forward queries) or the %GEOCODE_ERROR_NOT_SUPPORTED error (for reverse
diff --git a/geocode-glib/geocode-nominatim.c b/geocode-glib/geocode-nominatim.c
index ad95e35..92f2927 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,11 +1377,11 @@ 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.
  *
- * Returns: (transfer full): a new #GeocodeNominatim. Use g_object_unref() when done.
+ * Returns: (transfer full): a new #GeocodeNominatim. Use [method@GObject.Object.unref] when done.
  *
  * Since: 3.23.1
  */
@@ -1408,11 +1409,12 @@ 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.
+ * Returns: (transfer full): a new #GeocodeNominatim. Use [method@GObject.Object.unref] when done.
  *
  * Since: 3.23.1
  */
@@ -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..75668bf 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.
  **/
@@ -592,7 +593,7 @@ geocode_place_init (GeocodePlace *place)
  *
  * Creates a new #GeocodePlace object.
  *
- * Returns: a new #GeocodePlace object. Use g_object_unref() when done.
+ * Returns: a new #GeocodePlace object. Use [method@GObject.Object.unref] when done.
  **/
 GeocodePlace *
 geocode_place_new (const char      *name,
@@ -612,7 +613,7 @@ geocode_place_new (const char      *name,
  *
  * Creates a new #GeocodePlace object.
  *
- * Returns: a new #GeocodePlace object. Use g_object_unref() when done.
+ * Returns: a new #GeocodePlace object. Use [method@GObject.Object.unref] when done.
  **/
 GeocodePlace *
 geocode_place_new_with_location (const char      *name,
@@ -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..1db9fb8 100644
--- a/geocode-glib/geocode-reverse.c
+++ b/geocode-glib/geocode-reverse.c
@@ -81,9 +81,10 @@ 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.
+ * Returns: a new #GeocodeReverse. Use [method@GObject.Object.unref] when done.
  **/
 GeocodeReverse *
 geocode_reverse_new_for_location (GeocodeLocation *location)
@@ -213,10 +214,12 @@ 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.
+ * errors. Free the returned instance with [method@GObject.Object.unref] when done.
  **/
 GeocodePlace *
 geocode_reverse_resolve_finish (GeocodeReverse *object,
@@ -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.
@@ -246,7 +250,7 @@ geocode_reverse_resolve_finish (GeocodeReverse *object,
  * 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.
+ * errors. Free the returned instance with [method@GObject.Object.unref] when done.
  **/
 GeocodePlace *
 geocode_reverse_resolve (GeocodeReverse *object,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]