Commit 5a5813dd authored by James Westman's avatar James Westman Committed by James Westman
Browse files

Rewrite doc comments for gi-docgen

GI-Docgen uses a different format for links. Convert all the
documentation to use the new format.
parent e4a7b114
Pipeline #286161 passed with stage
in 1 minute and 45 seconds
......@@ -18,10 +18,12 @@
*/
/**
* SECTION:shumate-coordinate
* @short_description: The simplest implementation of #ShumateLocation
* ShumateCoordinate:
*
* #ShumateCoordinate is a simple object implementing #ShumateLocation.
* A coordinate on Earth's surface with a latitude and longitude.
*
* This is the simplest possible implementation of the [iface@Shumate.Location]
* interface.
*/
#include "shumate-coordinate.h"
......@@ -191,9 +193,9 @@ shumate_coordinate_init (ShumateCoordinate *coordinate)
/**
* shumate_coordinate_new:
*
* Creates a new instance of #ShumateCoordinate.
* Creates a new instance of [class@Shumate.Coordinate] with coordinates (0, 0).
*
* Returns: the created instance.
* Returns: the newly created instance
*/
ShumateCoordinate *
shumate_coordinate_new ()
......@@ -207,10 +209,10 @@ shumate_coordinate_new ()
* @latitude: the latitude coordinate
* @longitude: the longitude coordinate
*
* Creates a new instance of #ShumateCoordinate initialized with the given
* coordinates.
* Creates a new instance of [class@Shumate.Coordinate] initialized with the
* given coordinates.
*
* Returns: the created instance.
* Returns: the newly created instance
*/
ShumateCoordinate *
shumate_coordinate_new_full (double latitude,
......
......@@ -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,13 @@
*/
/**
* 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.
* Caches tiles on the filesystem.
*
* `ShumateFileCache` is 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
......@@ -308,7 +309,7 @@ shumate_file_cache_class_init (ShumateFileCacheClass *klass)
*
* The cache size limit in bytes.
*
* Note: this new value will not be applied until you call shumate_file_cache_purge()
* Note: this new value will not be applied until you call [method@FileCache.purge_cache_async].
*/
pspec = g_param_spec_uint ("size-limit",
"Size Limit",
......@@ -365,13 +366,13 @@ shumate_file_cache_init (ShumateFileCache *file_cache)
/**
* shumate_file_cache_new_full:
* @size_limit: maximum size of the cache in bytes
* @cache_key: an ID for the tileset to store/retrieve
* @cache_dir: (allow-none): the directory where the cache is created. When cache_dir == NULL,
* a cache in ~/.cache/shumate is used.
* @cache_key: the ID of the tileset to store/retrieve
* @cache_dir: (allow-none): the directory where the cache is created. When
* `cache_dir == NULL`, a cache in g_get_user_cache_dir()/shumate is used.
*
* Constructor of #ShumateFileCache.
* Creates a new [class@FileCache] with the given parameters.
*
* Returns: a constructed #ShumateFileCache
* Returns: the newly created instance
*/
ShumateFileCache *
shumate_file_cache_new_full (guint size_limit,
......@@ -393,7 +394,7 @@ shumate_file_cache_new_full (guint size_limit,
/**
* shumate_file_cache_get_size_limit:
* @file_cache: a #ShumateFileCache
* @file_cache: a [class@FileCache]
*
* Gets the cache size limit in bytes.
*
......@@ -412,7 +413,7 @@ shumate_file_cache_get_size_limit (ShumateFileCache *file_cache)
/**
* shumate_file_cache_get_cache_dir:
* @file_cache: a #ShumateFileCache
* @file_cache: a [class@FileCache]
*
* Gets the directory where the cache database is stored.
*
......@@ -431,7 +432,7 @@ shumate_file_cache_get_cache_dir (ShumateFileCache *file_cache)
/**
* shumate_file_cache_get_cache_key:
* @file_cache: a #ShumateFileCache
* @file_cache: a [class@FileCache]
*
* Gets the key used to store and retrieve tiles from the cache. Different keys
* can be used to store multiple tilesets in the same cache directory.
......@@ -451,7 +452,7 @@ shumate_file_cache_get_cache_key (ShumateFileCache *file_cache)
/**
* shumate_file_cache_set_size_limit:
* @file_cache: a #ShumateFileCache
* @file_cache: a [class@FileCache]
* @size_limit: the cache limit in bytes
*
* Sets the cache size limit in bytes.
......@@ -534,8 +535,8 @@ db_get_etag (ShumateFileCache *self, ShumateTile *tile)
/**
* shumate_file_cache_mark_up_to_date:
* @self: a #ShumateFileCache
* @tile: a #ShumateTile
* @self: a [class@FileCache]
* @tile: the tile to mark as up to date
*
* Marks a tile in the cache as being up to date, without changing its data.
*
......@@ -719,7 +720,7 @@ purge_cache (GTask *task,
/**
* shumate_file_cache_purge_cache_async:
* @self: a #ShumateFileCache
* @self: a [class@FileCache]
* @cancellable: (nullable): a #GCancellable
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
......@@ -754,7 +755,7 @@ shumate_file_cache_purge_cache_async (ShumateFileCache *self,
/**
* shumate_file_cache_purge_cache_finish:
* @self: a #ShumateFileCache
* @self: a [class@FileCache]
* @result: a #GAsyncResult provided to callback
* @error: a location for a #GError, or %NULL
*
......@@ -793,9 +794,9 @@ static void on_get_tile_file_loaded (GObject *source_object, GAsyncResult *res,
/**
* shumate_file_cache_get_tile_async:
* @self: a #ShumateFileCache
* @tile: a #ShumateTile
* @cancellable: (nullable): a #GCancellable
* @self: a [class@FileCache]
* @tile: a [class@Tile] containing the grid coordinates to get data for
* @cancellable: (nullable): a #GCancellable to cancel the operation
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
*
......@@ -879,13 +880,13 @@ on_get_tile_file_loaded (GObject *source_object, GAsyncResult *res, gpointer use
/**
* shumate_file_cache_get_tile_finish:
* @self: a #ShumateFileCache
* @self: a [class@FileCache]
* @etag: (nullable) (out) (optional): a location for the data's ETag, or %NULL
* @modtime: (nullable) (out) (optional): a location to return the tile's last modification time, or %NULL
* @result: a #GAsyncResult provided to callback
* @result: the #GAsyncResult provided to the callback
* @error: a location for a #GError, or %NULL
*
* Gets the tile data from a completed shumate_file_cache_get_tile_async()
* Gets the tile data from a completed [method@FileCache.get_tile_async]
* operation.
*
* @modtime will be set to the time the tile was added to the cache, or the
......@@ -940,11 +941,11 @@ static void on_file_written (GObject *object, GAsyncResult *result, gpointer use
/**
* shumate_file_cache_store_tile_async:
* @self: an #ShumateFileCache
* @tile: a #ShumateTile
* @bytes: a #GBytes
* @etag: (nullable): an ETag string, or %NULL
* @cancellable: (nullable): a #GCancellable
* @self: a [class@FileCache]
* @tile: a [class@Tile] containing the grid position to store data for
* @bytes: the data to store
* @etag: (nullable): an ETag string
* @cancellable: (nullable): a #GCancellable to cancel the operation
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
*
......@@ -1071,11 +1072,11 @@ on_file_written (GObject *object, GAsyncResult *res, gpointer user_data)
/**
* shumate_file_cache_store_tile_finish:
* @self: an #ShumateFileCache
* @result: a #GAsyncResult provided to callback
* @self: a [class@FileCache]
* @result: the #GAsyncResult provided to the callback
* @error: a location for a #GError, or %NULL
*
* Gets the success value of a completed shumate_file_cache_store_tile_async()
* Gets the success value of a completed [method@FileCache.store_tile_async]
* operation.
*
* Returns: %TRUE if the operation was successful, otherwise %FALSE
......@@ -1094,7 +1095,7 @@ shumate_file_cache_store_tile_finish (ShumateFileCache *self,
/**
* shumate_file_cache_error_quark:
*
* Gets the #ShumateFileCache error quark.
* Gets the [class@FileCache] error quark.
*
* Returns: a #GQuark
*/
......
......@@ -30,13 +30,6 @@
G_BEGIN_DECLS
/**
* SHUMATE_FILE_CACHE_ERROR:
*
* Error domain for errors that may occur while storing or retrieving tiles
* from a #ShumateFileCache. Errors in this domain will be from the
* #ShumateFileCacheError enum.
*/
#define SHUMATE_FILE_CACHE_ERROR shumate_file_cache_error_quark ()
GQuark shumate_file_cache_error_quark (void);
......@@ -44,7 +37,8 @@ GQuark shumate_file_cache_error_quark (void);
* ShumateFileCacheError:
* @SHUMATE_FILE_CACHE_ERROR_FAILED: An unspecified error occurred during the operation.
*
* Error codes in the #SHUMATE_FILE_CACHE_ERROR domain.
* Error domain for errors that may occur while storing or retrieving tiles
* from a [class@FileCache].
*/
typedef enum {
SHUMATE_FILE_CACHE_ERROR_FAILED,
......@@ -53,13 +47,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,12 @@
*/
/**
* 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.
* Base class for all map layers.
*
* Map layers define any content that is displayed in the map viewport, from
* the map itself to markers and paths.
*/
#include "shumate-layer.h"
......@@ -115,6 +116,11 @@ shumate_layer_class_init (ShumateLayerClass *klass)
object_class->dispose = shumate_layer_dispose;
object_class->constructed = shumate_layer_constructed;
/**
* ShumateLayer:viewport:
*
* The viewport used to display the layer.
*/
obj_properties[PROP_VIEWPORT] =
g_param_spec_object ("viewport",
"Viewport",
......@@ -140,11 +146,11 @@ shumate_layer_init (ShumateLayer *self)
/**
* shumate_layer_get_viewport:
* @self: a #ShumateLayer
* @self: a [class@Layer]
*
* Gets the #ShumateViewport used by this layer.
* Gets the [class@Viewport] used by this layer.
*
* Returns: (transfer none): The #ShumateViewport.
* Returns: (transfer none): The [class@Viewport].
*/
ShumateViewport *
shumate_layer_get_viewport (ShumateLayer *self)
......
......@@ -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 map license text.
*/
#include "config.h"
......@@ -143,9 +142,8 @@ shumate_license_class_init (ShumateLicenseClass *klass)
/**
* ShumateLicense:extra-text:
*
* Sets additional text to be displayed in the license area. The map's
* license will be added below it. Your text can have multiple lines, just use
* "\n" in between.
* Sets additional text to be displayed above the other license texts. Your
* text can have multiple lines, just use "\n" in between.
*/
obj_properties[PROP_EXTRA_TEXT] =
g_param_spec_string ("extra-text",
......@@ -209,9 +207,9 @@ shumate_license_init (ShumateLicense *self)
/**
* shumate_license_new:
*
* Creates an instance of #ShumateLicense.
* Creates an instance of [class@License].
*
* Returns: a new #ShumateLicense.
* Returns: the newly created instance
*/
ShumateLicense *
shumate_license_new (void)
......@@ -221,11 +219,11 @@ shumate_license_new (void)
/**
* shumate_license_set_extra_text:
* @license: a #ShumateLicense
* @license: a [class@License]
* @text: the additional license text
*
* Show the additional license text on the map view. The text will preceed the
* map's licence when displayed. Use "\n" to separate the lines.
* Sets additional text to be displayed above the other license texts.
* Multiline strings are allowed.
*/
void
shumate_license_set_extra_text (ShumateLicense *license,
......@@ -242,7 +240,7 @@ shumate_license_set_extra_text (ShumateLicense *license,
/**
* shumate_license_get_extra_text:
* @license: a #ShumateLicense
* @license: a [class@License]
*
* Gets the additional license text.
*
......@@ -259,10 +257,10 @@ shumate_license_get_extra_text (ShumateLicense *license)
/**
* shumate_license_set_xalign:
* @license: a #ShumateLicense
* @license: a [class@License]
* @xalign: The license's text horizontal alignment
*
* Set the license's text horizontal alignment.
* Sets the license's text horizontal alignment.
*/
void
shumate_license_set_xalign (ShumateLicense *license,
......@@ -279,9 +277,9 @@ shumate_license_set_xalign (ShumateLicense *license,
/**
* shumate_license_get_xalign:
* @license: The license
* @license: a [class@License]
*
* Get the license's text horizontal alignment.
* Gets the license's text horizontal alignment.
*
* Returns: the license's text horizontal alignment.
*/
......@@ -293,6 +291,13 @@ shumate_license_get_xalign (ShumateLicense *license)
return gtk_label_get_xalign (GTK_LABEL (license->license_label));
}
/**
* shumate_license_append_map_source:
* @license: a [class@License]
* @map_source: a map source to display license text for
*
* Appends license text from @map_source to the label.
*/
void
shumate_license_append_map_source (ShumateLicense *license,
ShumateMapSource *map_source)
......@@ -303,6 +308,13 @@ shumate_license_append_map_source (ShumateLicense *license,
shumate_license_sources_changed (license);
}
/**
* shumate_license_prepend_map_source:
* @license: a [class@License]
* @map_source: a map source to display license text for
*
* Prepends license text from @map_source to the label.
*/
void
shumate_license_prepend_map_source (ShumateLicense *license,
ShumateMapSource *map_source)
......@@ -313,6 +325,13 @@ shumate_license_prepend_map_source (ShumateLicense *license,
shumate_license_sources_changed (license);
}
/**
* shumate_license_remove_map_source:
* @license: a [class@License]
* @map_source: a map source to stop displaying license text for
*
* Removes the license text from @map_source from the label.
*/
void
shumate_license_remove_map_source (ShumateLicense *license,
ShumateMapSource *map_source)
......
......@@ -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,
......
......@@ -17,10 +17,11 @@
* 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:
*
* By implementing #ShumateLocation the object declares that it has latitude
* An interface common to objects having latitude and longitude.
*
* By implementing [iface@Location] the object declares that it has latitude
* and longitude and can be used to specify location on the map.
*/
......@@ -35,12 +36,12 @@ shumate_location_default_init (ShumateLocationInterface *iface)
/**
* ShumateLocation:longitude:
*
* The longitude coordonate in degrees
* The longitude coordinate in degrees.
*/
g_object_interface_install_property (iface,
g_param_spec_double ("longitude",
"Longitude",
"The longitude coordonate in degrees",
"The longitude coordinate in degrees",
-180.0f,
180.0f,
0.0f,
......@@ -49,12 +50,12 @@ shumate_location_default_init (ShumateLocationInterface *iface)
/**
* ShumateLocation:latitude:
*
* The latitude coordonate in degrees
* The latitude coordinate in degrees.
*/
g_object_interface_install_property (iface,
g_param_spec_double ("latitude",
"Latitude",
"The latitude coordonate in degrees",
"The latitude coordinate in degrees",
-90.0f,
90.0f,
0.0f,
......@@ -64,11 +65,11 @@ shumate_location_default_init (ShumateLocationInterface *iface)
/**
* shumate_location_set_location:
* @location: a #ShumateLocation
* @location: a [iface@Location]
* @latitude: the latitude in degrees
* @longitude: the longitude in degrees
*
* Sets the coordinates of the location
* Sets the coordinates of the location.
*/
void
shumate_location_set_location (ShumateLocation *location,
......@@ -83,7 +84,7 @@ shumate_location_set_location (ShumateLocation *location,
/**
* shumate_location_get_latitude:
* @location: a #ShumateLocation
* @location: a [iface@Location]
*
* Gets the latitude coordinate in degrees.
*
......@@ -98,7 +99,7 @@ shumate_location_get_latitude (ShumateLocation *location)
/**
* shumate_location_get_longitude:
* @location: a #ShumateLocation
* @location: a [iface@Location]
*
* Gets the longitude coordinate in degrees.
*
......
......@@ -36,20 +36,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.
* @get_longitude: virtual function for obtaining longitude.
* @set_location: virtual function for setting position.
*
* An interface common to objects having latitude and longitude.
*/
struct _ShumateLocationInterface
{
/*< private >*/
......
......@@ -21,6 +21,12 @@
#include "shumate-view.h"
#include "shumate-memory-cache.h"
/**
* ShumateMapLayer:
*
* A [class@Layer] that displays a base map.
*/
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);
......
......@@ -19,10 +19,9 @@
*/
/**
* SECTION:shumate-map-source-desc
* @short_description: A class that describes map sources.
* ShumateMapSourceDesc
*
* A class that describes map sources.
* Describes a map source.
*/
#include "shumate-map-source-desc.h"
......@@ -212,7 +211,7 @@ shumate_map_source_desc_class_init (ShumateMapSourceDescClass *klass)
/**
* ShumateMapSourceDesc:id:
*
* The id of the map source
* The ID of the map source
*/
obj_properties[PROP_ID] =
g_param_spec_string ("id",
......@@ -224,7 +223,7 @@ shumate_map_source_desc_class_init (ShumateMapSourceDescClass *klass)
/**
* ShumateMapSourceDesc:name:
*
* The name of the map source
* The display name of the map source
*/
obj_properties[PROP_NAME] =
g_param_spec_string ("name",
......@@ -236,7 +235,7 @@ shumate_map_source_desc_class_init (ShumateMapSourceDescClass *klass)
/**
* ShumateMapSourceDesc:license:
*
* The license of the map source
* The license text of the map source
*/
obj_properties[PROP_LICENSE] =
g_param_spec_string ("license",
......@@ -248,7 +247,7 @@ shumate_map_source_desc_class_init (ShumateMapSourceDescClass *klass)
/**
* ShumateMapSourceDesc:license-uri:
*