Commit 7a0a03f2 authored by Niels De Graef's avatar Niels De Graef 😁
Browse files

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.
parent a6b1e3c7
Pipeline #323447 passed with stages
in 2 minutes and 40 seconds
......@@ -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',
......
......@@ -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".
*/
......
......@@ -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"
......
......@@ -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;
......
......@@ -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
......
......@@ -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;
......
......@@ -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"
......
......@@ -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;
......
......@@ -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"
......
......@@ -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,
......
......@@ -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.
......
......@@ -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.
......
......@@ -20,6 +20,11 @@
#include "shumate-map-layer.h"
#include "shumate-memory-cache.h"
/**
* ShumateMapLayer:
*
*/
struct _ShumateMapLayer
{
ShumateLayer parent_instance;
......
......@@ -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);
......
......@@ -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
......
......@@ -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.
*/
......
......@@ -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;
......
......@@ -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,
......
......@@ -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;
......
......@@ -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"
......
Supports Markdown
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