[libshumate/feature/gi-docgen-section-annotations] docs: Update gi-docgen annotations

From: Niels De Graef <nielsdg src gnome org>
To: commits-list gnome org
Cc:
Subject: [libshumate/feature/gi-docgen-section-annotations] docs: Update gi-docgen annotations
Date: Wed, 6 Oct 2021 20:18:37 +0000 (UTC)

commit 7a0a03f299881e8faaac7d904cc47b74795ae5dd
Author: Niels De Graef <nielsdegraef gmail com>
Date:   Wed Oct 6 22:11:53 2021 +0200

    docs: Update gi-docgen annotations
    
    The whole `SECTION` block is a gtk-doc specific annotation. Just
    immediately document the class/struct/interface with the usual docs
    syntax and gi-docgen will know what to do with it. There's also no
    worrying about exposed structs, since there are none in libshumate, and
    even if there were, you would still have to document them in the GIR.
    
    Finally, use proper linking as specified by the gi-docgen tutorial.

 meson_options.txt                     |  2 +-
 shumate/shumate-compass.c             |  9 ++++-----
 shumate/shumate-coordinate.c          |  5 ++---
 shumate/shumate-coordinate.h          |  7 -------
 shumate/shumate-file-cache.c          |  9 ++++-----
 shumate/shumate-file-cache.h          |  7 -------
 shumate/shumate-layer.c               |  7 +++++--
 shumate/shumate-layer.h               |  7 -------
 shumate/shumate-license.c             |  5 ++---
 shumate/shumate-license.h             |  7 -------
 shumate/shumate-location.c            |  6 ++++--
 shumate/shumate-location.h            |  6 ------
 shumate/shumate-map-layer.c           |  5 +++++
 shumate/shumate-map-layer.h           |  7 -------
 shumate/shumate-map-source-registry.c | 11 +++++------
 shumate/shumate-map-source.c          | 11 +++++------
 shumate/shumate-map-source.h          |  7 -------
 shumate/shumate-map.c                 | 28 ++++++++++------------------
 shumate/shumate-map.h                 |  7 -------
 shumate/shumate-marker-layer.c        |  7 +++----
 shumate/shumate-marker-layer.h        |  7 -------
 shumate/shumate-marker.c              | 13 ++++++-------
 shumate/shumate-marker.h              |  7 -------
 shumate/shumate-memory-cache.c        | 10 ++++------
 shumate/shumate-memory-cache.h        |  7 -------
 shumate/shumate-network-tile-source.c | 13 ++++++-------
 shumate/shumate-network-tile-source.h |  7 -------
 shumate/shumate-path-layer.c          | 10 +++++-----
 shumate/shumate-path-layer.h          |  7 -------
 shumate/shumate-point.c               |  7 +++----
 shumate/shumate-point.h               |  7 -------
 shumate/shumate-scale.c               | 10 ++++------
 shumate/shumate-scale.h               |  7 -------
 shumate/shumate-tile.c                |  6 +++---
 shumate/shumate-tile.h                |  8 --------
 shumate/shumate-viewport.c            |  6 +++---
 36 files changed, 84 insertions(+), 208 deletions(-)
---
diff --git a/meson_options.txt b/meson_options.txt
index ad9ae50..f7a6938 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -6,7 +6,7 @@ option('vapi',
        description: 'Generate vapi data (requires vapigen)')
 
 option('gtk_doc',
-       type: 'boolean', value: false,
+       type: 'boolean', value: true,
        description: 'Build reference manual (requires gi-docgen installed and gir enabled)')
 
 option('demos',
diff --git a/shumate/shumate-compass.c b/shumate/shumate-compass.c
index b43ab0f..457b977 100644
--- a/shumate/shumate-compass.c
+++ b/shumate/shumate-compass.c
@@ -18,20 +18,19 @@
  */
 
 /**
- * SECTION:shumate-compass
- * @short_description: A widget displaying a compass.
+ * ShumateCompass:
  *
  * A widget displaying a compass.
  *
  * # CSS nodes
  *
- * |[<!-- language="plain" -->
+ * ```
  * map-compass
  * ├── revealer
  * ├──── image
- * ]|
+ * ```
  *
- * ShumateCompass uses a single CSS node with name map-compass. It also uses an
+ * `ShumateCompass` uses a single CSS node with name map-compass. It also uses an
  * image named "map-compass".
  */
 
diff --git a/shumate/shumate-coordinate.c b/shumate/shumate-coordinate.c
index 8dc59e8..f9d5149 100644
--- a/shumate/shumate-coordinate.c
+++ b/shumate/shumate-coordinate.c
@@ -18,10 +18,9 @@
  */
 
 /**
- * SECTION:shumate-coordinate
- * @short_description: The simplest implementation of #ShumateLocation
+ * ShumateCoordinate:
  *
- * #ShumateCoordinate is a simple object implementing #ShumateLocation.
+ * A simple object implementing [iface@Location].
  */
 
 #include "shumate-coordinate.h"
diff --git a/shumate/shumate-coordinate.h b/shumate/shumate-coordinate.h
index d179c52..b8d3222 100644
--- a/shumate/shumate-coordinate.h
+++ b/shumate/shumate-coordinate.h
@@ -33,13 +33,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_COORDINATE shumate_coordinate_get_type ()
 G_DECLARE_DERIVABLE_TYPE (ShumateCoordinate, shumate_coordinate, SHUMATE, COORDINATE, GInitiallyUnowned)
 
-/**
- * ShumateCoordinate:
- *
- * The #ShumateCoordinate structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateCoordinateClass
 {
   GInitiallyUnownedClass parent_class;
diff --git a/shumate/shumate-file-cache.c b/shumate/shumate-file-cache.c
index e81055a..b5adee8 100644
--- a/shumate/shumate-file-cache.c
+++ b/shumate/shumate-file-cache.c
@@ -19,12 +19,11 @@
  */
 
 /**
- * SECTION:shumate-file-cache
- * @short_description: Caches tiles on the filesystem
+ * ShumateFileCache:
  *
- * #ShumateFileCache is a cache that stores and retrieves tiles from the
- * file system. It is mainly used by #ShumateNetworkTileSource, but can also
- * be used by custom map sources.
+ * A cache that stores and retrieves tiles from the file system. It is mainly
+ * used by [class@NetworkTileSource], but can also be used by custom map
+ * sources.
  *
  * The cache will be filled up to a certain size limit. When this limit is
  * reached, the cache can be purged, and the tiles that are accessed least are
diff --git a/shumate/shumate-file-cache.h b/shumate/shumate-file-cache.h
index 1edff8a..bf55a4d 100644
--- a/shumate/shumate-file-cache.h
+++ b/shumate/shumate-file-cache.h
@@ -53,13 +53,6 @@ typedef enum {
 #define SHUMATE_TYPE_FILE_CACHE shumate_file_cache_get_type ()
 G_DECLARE_DERIVABLE_TYPE (ShumateFileCache, shumate_file_cache, SHUMATE, FILE_CACHE, GObject)
 
-/**
- * ShumateFileCache:
- *
- * The #ShumateFileCache structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateFileCacheClass
 {
   GObjectClass parent_class;
diff --git a/shumate/shumate-layer.c b/shumate/shumate-layer.c
index 7b04334..c2122c0 100644
--- a/shumate/shumate-layer.c
+++ b/shumate/shumate-layer.c
@@ -18,11 +18,14 @@
  */
 
 /**
- * SECTION:shumate-layer
- * @short_description: Base class of libshumate layers
+ * ShumateLayer:
  *
  * Every layer (overlay that moves together with the map) has to inherit this
  * class and implement its virtual methods.
+ *
+ * You can use the same layer to display many types of maps.  In Shumate they
+ * are called map sources.  You can change the [property@MapLayer:map-source]
+ * property at any time to replace the current displayed map.
  */
 
 #include "shumate-layer.h"
diff --git a/shumate/shumate-layer.h b/shumate/shumate-layer.h
index 179267f..ff699e6 100644
--- a/shumate/shumate-layer.h
+++ b/shumate/shumate-layer.h
@@ -32,13 +32,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_LAYER shumate_layer_get_type ()
 G_DECLARE_DERIVABLE_TYPE (ShumateLayer, shumate_layer, SHUMATE, LAYER, GtkWidget)
 
-/**
- * ShumateLayer:
- *
- * The #ShumateLayer structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateLayerClass
 {
   GtkWidgetClass parent_class;
diff --git a/shumate/shumate-license.c b/shumate/shumate-license.c
index 20ab3ef..4db7b8c 100644
--- a/shumate/shumate-license.c
+++ b/shumate/shumate-license.c
@@ -18,10 +18,9 @@
  */
 
 /**
- * SECTION:shumate-license
- * @short_description: An actor that displays license text.
+ * ShumateLicense:
  *
- * An actor that displays license text.
+ * A widget that displays license text.
  */
 
 #include "shumate-license.h"
diff --git a/shumate/shumate-license.h b/shumate/shumate-license.h
index 8e800f5..d28fc3e 100644
--- a/shumate/shumate-license.h
+++ b/shumate/shumate-license.h
@@ -34,13 +34,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_LICENSE shumate_license_get_type ()
 G_DECLARE_FINAL_TYPE (ShumateLicense, shumate_license, SHUMATE, LICENSE, GtkWidget)
 
-/**
- * ShumateLicense:
- *
- * The #ShumateLicense structure contains only private data
- * and should be accessed using the provided API
- */
-
 ShumateLicense *shumate_license_new (void);
 
 void shumate_license_set_extra_text (ShumateLicense *license,
diff --git a/shumate/shumate-location.c b/shumate/shumate-location.c
index 98e21ac..b0629eb 100644
--- a/shumate/shumate-location.c
+++ b/shumate/shumate-location.c
@@ -16,9 +16,11 @@
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  */
+
 /**
- * SECTION:shumate-location
- * @short_description: An interface common to objects having latitude and longitude
+ * ShumateLocation:
+ *
+ * An interface common to objects having latitude and longitude
  *
  * By implementing #ShumateLocation the object declares that it has latitude
  * and longitude and can be used to specify location on the map.
diff --git a/shumate/shumate-location.h b/shumate/shumate-location.h
index bc7caa0..83a763c 100644
--- a/shumate/shumate-location.h
+++ b/shumate/shumate-location.h
@@ -59,12 +59,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_LOCATION (shumate_location_get_type ())
 G_DECLARE_INTERFACE (ShumateLocation, shumate_location, SHUMATE, LOCATION, GObject)
 
-/**
- * ShumateLocation:
- *
- * An interface common to objects having latitude and longitude.
- */
-
 /**
  * ShumateLocationInterface:
  * @get_latitude: virtual function for obtaining latitude.
diff --git a/shumate/shumate-map-layer.c b/shumate/shumate-map-layer.c
index 0fd0786..b88c813 100644
--- a/shumate/shumate-map-layer.c
+++ b/shumate/shumate-map-layer.c
@@ -20,6 +20,11 @@
 #include "shumate-map-layer.h"
 #include "shumate-memory-cache.h"
 
+/**
+ * ShumateMapLayer:
+ *
+ */
+
 struct _ShumateMapLayer
 {
   ShumateLayer parent_instance;
diff --git a/shumate/shumate-map-layer.h b/shumate/shumate-map-layer.h
index 2f45617..55d97a6 100644
--- a/shumate/shumate-map-layer.h
+++ b/shumate/shumate-map-layer.h
@@ -32,13 +32,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_MAP_LAYER shumate_map_layer_get_type ()
 G_DECLARE_FINAL_TYPE (ShumateMapLayer, shumate_map_layer, SHUMATE, MAP_LAYER, ShumateLayer)
 
-/**
- * ShumateMapLayer:
- *
- * The #ShumateMapLayer structure contains only private data
- * and should be accessed using the provided API
- */
-
 ShumateMapLayer *shumate_map_layer_new (ShumateMapSource *map_source,
                                         ShumateViewport  *viewport);
 
diff --git a/shumate/shumate-map-source-registry.c b/shumate/shumate-map-source-registry.c
index f690713..691767f 100644
--- a/shumate/shumate-map-source-registry.c
+++ b/shumate/shumate-map-source-registry.c
@@ -21,13 +21,12 @@
  */
 
 /**
- * SECTION:shumate-map-source-registry
- * @short_description: An object holding #ShumateMapSource
+ * ShumateMapSourceRegistry:
  *
- * This object allows you to hold #ShumateMapSource instances, you can access a
- * default set of sources with shumate_map_source_registry_populate_defaults().
+ * This object allows you to hold [class@MapSource] instances, you can access a
+ * default set of sources with [method@MapSourceRegistry.populate_defaults].
  *
- * It conveniently implements #GListModel to easily integrate with it.
+ * It conveniently implements [iface@Gio.ListModel] to easily integrate with it.
  */
 
 #include "shumate-map-source-registry.h"
@@ -130,7 +129,7 @@ shumate_map_source_registry_new (void)
  * shumate_map_source_registry_new_with_defaults:
  *
  * Create a new #ShumateMapSourceRegistry with defaults map sources.
- * This is identical to calling shumate_map_source_registry_populate_defaults()
+ * This is identical to calling [method@MapSourceRegistry.populate_defaults]
  * after shumate_map_source_registry_new().
  *
  * Returns: (transfer full): a newly created #ShumateMapSourceRegistry
diff --git a/shumate/shumate-map-source.c b/shumate/shumate-map-source.c
index 422b108..3f6509e 100644
--- a/shumate/shumate-map-source.c
+++ b/shumate/shumate-map-source.c
@@ -18,14 +18,13 @@
  */
 
 /**
- * SECTION:shumate-map-source
- * @short_description: A base class for map sources
+ * ShumateMapSource:
  *
- * #ShumateMapSource is the base class for all map sources. Map sources fill
- * #ShumateTile objects with images from various sources: a web API, for
- * example, or a test pattern generated on demand.
+ * The base class for all map sources. Map sources fill [class@Tile] objects
+ * with images from various sources: a web API, for example, or a test pattern
+ * generated on demand.
  *
- * The most common map source is #ShumateNetworkTileSource, which fetches tiles
+ * The most common map source is [class@NetworkTileSource], which fetches tiles
  * from an API.
  */
 
diff --git a/shumate/shumate-map-source.h b/shumate/shumate-map-source.h
index b29aebc..51a9c62 100644
--- a/shumate/shumate-map-source.h
+++ b/shumate/shumate-map-source.h
@@ -42,13 +42,6 @@ typedef enum
   SHUMATE_MAP_PROJECTION_MERCATOR
 } ShumateMapProjection;
 
-/**
- * ShumateMapSource:
- *
- * The #ShumateMapSource structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateMapSourceClass
 {
   GObjectClass parent_class;
diff --git a/shumate/shumate-map.c b/shumate/shumate-map.c
index 64bb2d6..7609fe3 100644
--- a/shumate/shumate-map.c
+++ b/shumate/shumate-map.c
@@ -22,26 +22,18 @@
  */
 
 /**
- * SECTION:shumate-view
- * @short_description: A #GtkWidget to display maps
+ * ShumateMap:
  *
- * The #ShumateMap is a #GtkWidget to display maps.  It supports two modes
- * of scrolling:
- * <itemizedlist>
- *   <listitem><para>Push: the normal behavior where the maps don't move
- *   after the user stopped scrolling;</para></listitem>
- *   <listitem><para>Kinetic: the behavior where the maps decelerate after
- *   the user stopped scrolling.</para></listitem>
- * </itemizedlist>
+ * A [class@Gtk.Widget] to display maps. It supports two modes of scrolling:
  *
- * You can use the same #ShumateMap to display many types of maps.  In
- * Shumate they are called map sources.  You can change the #map-source
- * property at anytime to replace the current displayed map.
+ * - Push: the normal behavior where the maps don't move after the user stopped
+ *   scrolling;
+ * - Kinetic: the behavior where the maps decelerate after the user stopped
+ *   scrolling.
  *
  * The maps are downloaded from Internet from open maps sources (like
- * <ulink role="online-location"
- * url="http://www.openstreetmap.org";>OpenStreetMap</ulink>).  Maps are divided
- * in tiles for each zoom level.  When a tile is requested, #ShumateMap will
+ * [OpenStreetMap](http://www.openstreetmap.org";)). Maps are divided
+ * in tiles for each zoom level. When a tile is requested, `ShumateMap` will
  * first check if it is in cache (in the user's cache dir under shumate). If
  * an error occurs during download, an error tile will be displayed.
  */
@@ -1001,7 +993,7 @@ shumate_map_go_to (ShumateMap *self,
  *
  * Get the 'go-to-duration' property.
  *
- * Returns: the animation duration when calling shumate_map_go_to(),
+ * Returns: the animation duration when calling [method@Map.go_to],
  *   in milliseconds.
  */
 guint
@@ -1019,7 +1011,7 @@ shumate_map_get_go_to_duration (ShumateMap *self)
  * @self: a #ShumateMap
  * @duration: the animation duration, in milliseconds
  *
- * Set the duration of the transition of shumate_map_go_to().
+ * Set the duration of the transition of [method@Map.go_to].
  */
 void
 shumate_map_set_go_to_duration (ShumateMap *self,
diff --git a/shumate/shumate-map.h b/shumate/shumate-map.h
index 2914b49..28f111c 100644
--- a/shumate/shumate-map.h
+++ b/shumate/shumate-map.h
@@ -38,13 +38,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_MAP shumate_map_get_type ()
 G_DECLARE_DERIVABLE_TYPE (ShumateMap, shumate_map, SHUMATE, MAP, GtkWidget)
 
-/**
- * ShumateMap:
- *
- * The #ShumateMap structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateMapClass
 {
   GtkWidgetClass parent_class;
diff --git a/shumate/shumate-marker-layer.c b/shumate/shumate-marker-layer.c
index 8e4a0d0..22c751f 100644
--- a/shumate/shumate-marker-layer.c
+++ b/shumate/shumate-marker-layer.c
@@ -19,11 +19,10 @@
  */
 
 /**
- * SECTION:shumate-marker-layer
- * @short_description: A container for #ShumateMarker
+ * ShumateMarkerLayer:
  *
- * A ShumateMarkerLayer displays markers on the map. It is responsible for
- * positioning markers correctly, marker selections and group marker operations.
+ * Displays markers on the map. It is responsible for positioning markers
+ * correctly, marker selections and group marker operations.
  */
 
 #include "shumate-marker-layer.h"
diff --git a/shumate/shumate-marker-layer.h b/shumate/shumate-marker-layer.h
index 12dacff..741e364 100644
--- a/shumate/shumate-marker-layer.h
+++ b/shumate/shumate-marker-layer.h
@@ -37,13 +37,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_MARKER_LAYER shumate_marker_layer_get_type ()
 G_DECLARE_DERIVABLE_TYPE (ShumateMarkerLayer, shumate_marker_layer, SHUMATE, MARKER_LAYER, ShumateLayer)
 
-/**
- * ShumateMarkerLayer:
- *
- * The #ShumateMarkerLayer structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateMarkerLayerClass
 {
   ShumateLayerClass parent_class;
diff --git a/shumate/shumate-marker.c b/shumate/shumate-marker.c
index 78b956f..59cce32 100644
--- a/shumate/shumate-marker.c
+++ b/shumate/shumate-marker.c
@@ -19,16 +19,15 @@
  */
 
 /**
- * SECTION:shumate-marker
- * @short_description: Base widget representing a marker
+ * ShumateMarker:
  *
  * Markers represent points of interest on a map. Markers need to be
- * placed on a layer (a #ShumateMarkerLayer). Layers have to be added to a
- * #ShumateView for the markers to show on the map.
+ * placed on a layer (a [class@MarkerLayer]). Layers have to be added to a
+ * [class@Map] for the markers to show on the map.
  *
- * A marker is nothing more than a regular #GtkWidget. You can draw on it what
- * ever you want. Set the marker's position on the map using
- * shumate_location_set_location().
+ * A marker is nothing more than a regular [class@Gtk.Widget]. You can draw on
+ * it what ever you want. Set the marker's position on the map using
+ * [method@Location.set_location].
  *
  * This is a base class of all markers. libshumate has a more evoluted
  * type of markers with text and image support.
diff --git a/shumate/shumate-marker.h b/shumate/shumate-marker.h
index 3f50b55..74348c3 100644
--- a/shumate/shumate-marker.h
+++ b/shumate/shumate-marker.h
@@ -36,13 +36,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_MARKER shumate_marker_get_type ()
 G_DECLARE_DERIVABLE_TYPE (ShumateMarker, shumate_marker, SHUMATE, MARKER, GtkWidget)
 
-/**
- * ShumateMarker:
- *
- * The #ShumateMarker structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateMarkerClass
 {
   GtkWidgetClass parent_class;
diff --git a/shumate/shumate-memory-cache.c b/shumate/shumate-memory-cache.c
index acbe5d7..af49816 100644
--- a/shumate/shumate-memory-cache.c
+++ b/shumate/shumate-memory-cache.c
@@ -18,13 +18,11 @@
  */
 
 /**
- * SECTION:shumate-memory-cache
- * @short_description: Stores and loads cached tiles from the memory
+ * ShumateMemoryCache:
  *
- * #ShumateMemoryCache is a cache that stores and retrieves tiles from the
- * memory. The cache contents is not preserved between application restarts
- * so this cache serves mostly as a quick access temporary cache to the
- * most recently used tiles.
+ * A cache that stores and retrieves tiles from the memory. The cache contents
+ * is not preserved between application restarts so this cache serves mostly as
+ * a quick access temporary cache to the most recently used tiles.
  */
 
 #include "shumate-memory-cache.h"
diff --git a/shumate/shumate-memory-cache.h b/shumate/shumate-memory-cache.h
index 3382023..835115f 100644
--- a/shumate/shumate-memory-cache.h
+++ b/shumate/shumate-memory-cache.h
@@ -32,13 +32,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_MEMORY_CACHE shumate_memory_cache_get_type ()
 G_DECLARE_DERIVABLE_TYPE (ShumateMemoryCache, shumate_memory_cache, SHUMATE, MEMORY_CACHE, GObject)
 
-/**
- * ShumateMemoryCache:
- *
- * The #ShumateMemoryCache structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateMemoryCacheClass
 {
   GObjectClass parent_class;
diff --git a/shumate/shumate-network-tile-source.c b/shumate/shumate-network-tile-source.c
index 40bdb06..a25d090 100644
--- a/shumate/shumate-network-tile-source.c
+++ b/shumate/shumate-network-tile-source.c
@@ -19,15 +19,14 @@
  */
 
 /**
- * SECTION:shumate-network-tile-source
- * @short_description: A map source that downloads tile data from a web server
+ * ShumateNetworkTileSource:
  *
- * #ShumateNetworkTileSource fetches raster (that is, image) tiles from a
- * web API such as Mapbox or OpenStreetMap. It has a built-in #ShumateFileCache
- * to avoid repeated downloads.
+ * Fetches raster (that is, image) tiles from a web API such as Mapbox or
+ * OpenStreetMap. It has a built-in [class@FileCache] to avoid repeated
+ * downloads.
  *
  * Some preconfigured network map sources are built-in this library,
- * see #ShumateMapSourceFactory.
+ * see [class@MapSourceRegistry].
  */
 
 #include "shumate-network-tile-source.h"
@@ -383,7 +382,7 @@ shumate_network_tile_source_new_full (const char *id,
  * Default constructor of #ShumateNetworkTileSource.
  *
  * Returns: A URI format used for URI creation when downloading tiles. See
- * shumate_network_tile_source_set_uri_format() for more information.
+ * [method@NetworkTileSource.set_uri_format] for more information.
  */
 const char *
 shumate_network_tile_source_get_uri_format (ShumateNetworkTileSource *tile_source)
diff --git a/shumate/shumate-network-tile-source.h b/shumate/shumate-network-tile-source.h
index 94a0f3a..0332a97 100644
--- a/shumate/shumate-network-tile-source.h
+++ b/shumate/shumate-network-tile-source.h
@@ -62,13 +62,6 @@ typedef enum {
 #define SHUMATE_TYPE_NETWORK_TILE_SOURCE shumate_network_tile_source_get_type ()
 G_DECLARE_DERIVABLE_TYPE (ShumateNetworkTileSource, shumate_network_tile_source, SHUMATE, 
NETWORK_TILE_SOURCE, ShumateMapSource)
 
-/**
- * ShumateNetworkTileSource:
- *
- * The #ShumateNetworkTileSource structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateNetworkTileSourceClass
 {
   ShumateMapSourceClass parent_class;
diff --git a/shumate/shumate-path-layer.c b/shumate/shumate-path-layer.c
index c24a6b2..6900b75 100644
--- a/shumate/shumate-path-layer.c
+++ b/shumate/shumate-path-layer.c
@@ -19,13 +19,13 @@
  */
 
 /**
- * SECTION:shumate-path-layer
- * @short_description: A layer displaying line path between inserted #ShumateLocation
- * objects
+ * ShumatePathLayer:
+ *
+ * A layer displaying line path between inserted [iface@Location] objects
  *
  * This layer shows a connection between inserted objects implementing the
- * #ShumateLocation interface. This means that both #ShumateMarker
- * objects and #ShumateCoordinate objects can be inserted into the layer.
+ * [iface@Location] interface. This means that both #ShumateMarker
+ * objects and [class@Coordinate] objects can be inserted into the layer.
  * Of course, custom objects implementing the #ShumateLocation interface
  * can be used as well.
  */
diff --git a/shumate/shumate-path-layer.h b/shumate/shumate-path-layer.h
index 0b1dd6c..4e8f157 100644
--- a/shumate/shumate-path-layer.h
+++ b/shumate/shumate-path-layer.h
@@ -36,13 +36,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_PATH_LAYER shumate_path_layer_get_type ()
 G_DECLARE_DERIVABLE_TYPE (ShumatePathLayer, shumate_path_layer, SHUMATE, PATH_LAYER, ShumateLayer)
 
-/**
- * ShumatePathLayer:
- *
- * The #ShumatePathLayer structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumatePathLayerClass
 {
   ShumateLayerClass parent_class;
diff --git a/shumate/shumate-point.c b/shumate/shumate-point.c
index 71b98e0..37f9cf2 100644
--- a/shumate/shumate-point.c
+++ b/shumate/shumate-point.c
@@ -18,11 +18,10 @@
  */
 
 /**
- * SECTION:shumate-point
- * @short_description: A simple point to mark a coordinate
+ * ShumatePoint:
  *
- * #ShumatePoint is a simple variant of #ShumateMarker showing the location of
- * the point as a circle on the map.
+ * A simple variant of [class@Marker] showing the location of the point as a
+ * circle on the map.
  */
 
 #include "shumate-point.h"
diff --git a/shumate/shumate-point.h b/shumate/shumate-point.h
index 91c49d3..64456ef 100644
--- a/shumate/shumate-point.h
+++ b/shumate/shumate-point.h
@@ -34,13 +34,6 @@ G_BEGIN_DECLS
 #define SHUMATE_TYPE_POINT shumate_point_get_type ()
 G_DECLARE_FINAL_TYPE (ShumatePoint, shumate_point, SHUMATE, POINT, ShumateMarker)
 
-/**
- * ShumatePoint:
- *
- * The #ShumatePoint structure contains only private data
- * and should be accessed using the provided API
- */
-
 ShumateMarker *shumate_point_new (void);
 
 G_END_DECLS
diff --git a/shumate/shumate-scale.c b/shumate/shumate-scale.c
index 1eeb816..75ddf9e 100644
--- a/shumate/shumate-scale.c
+++ b/shumate/shumate-scale.c
@@ -20,21 +20,19 @@
  */
 
 /**
- * SECTION:shumate-scale
- * @short_description: A widget displaying a scale.
+ * ShumateScale:
  *
  * A widget displaying a scale.
  *
  * # CSS nodes
  *
- * |[<!-- language="plain" -->
+ * ```
  * map-scale
  * ├── label[.metric][.imperial]
- * ]|
+ * ```
  *
- * ShumateScale uses a single CSS node with name map-scale, it has up to two
+ * `ShumateScale` uses a single CSS node with name map-scale, it has up to two
  * childs different labels.
-
  */
 
 #include "shumate-scale.h"
diff --git a/shumate/shumate-scale.h b/shumate/shumate-scale.h
index 8c1c0f8..6eef419 100644
--- a/shumate/shumate-scale.h
+++ b/shumate/shumate-scale.h
@@ -51,13 +51,6 @@ typedef enum
   SHUMATE_UNIT_IMPERIAL,
 } ShumateUnit;
 
-/**
- * ShumateScale:
- *
- * The #ShumateScale structure contains only private data
- * and should be accessed using the provided API
- */
-
 ShumateScale *shumate_scale_new (ShumateViewport *viewport);
 
 guint shumate_scale_get_max_width (ShumateScale *scale);
diff --git a/shumate/shumate-tile.c b/shumate/shumate-tile.c
index 3aa56b7..ab173e6 100644
--- a/shumate/shumate-tile.c
+++ b/shumate/shumate-tile.c
@@ -19,11 +19,11 @@
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  */
+
 /**
- * SECTION:shumate-tile
- * @short_description: An object that represent map tiles
+ * ShumateTile:
  *
- * This object represents map tiles. Tiles are loaded by #ShumateMapSource.
+ * An object that represents map tiles. Tiles are loaded by a [class@MapSource].
  */
 
 #include "shumate-tile.h"
diff --git a/shumate/shumate-tile.h b/shumate/shumate-tile.h
index aed0e80..9c7ded6 100644
--- a/shumate/shumate-tile.h
+++ b/shumate/shumate-tile.h
@@ -48,14 +48,6 @@ typedef enum
   SHUMATE_STATE_DONE
 } ShumateState;
 
-
-/**
- * ShumateTile:
- *
- * The #ShumateTile structure contains only private data
- * and should be accessed using the provided API
- */
-
 struct _ShumateTileClass
 {
   GtkWidgetClass parent_class;
diff --git a/shumate/shumate-viewport.c b/shumate/shumate-viewport.c
index 770e205..ab7e63e 100644
--- a/shumate/shumate-viewport.c
+++ b/shumate/shumate-viewport.c
@@ -28,9 +28,9 @@
 #include "shumate-location.h"
 
 /**
- * SECTION:shumate-viewport
- * @short_description: The Object holding the coordinate and zoom-level state of
- * the current view.
+ * ShumateViewport:
+ *
+ * The object holding the coordinate and zoom-level state of the current view.
  */
 
 struct _ShumateViewport
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]