[libshumate/tintou/doc-update] Enhance the documentation coverage

[Corentin Noël <corentinnoel src gnome org>]

commit 74c355a14040e6ecb12966c80d3f9b3a2d64d1cf
Author: Corentin Noël <corentin noel collabora com>
Date:   Thu Apr 14 10:08:55 2022 +0200

    Enhance the documentation coverage
    
    Document the basics of each classes.

 shumate/shumate-data-source.c     |  6 ++++++
 shumate/shumate-map-layer.c       |  2 ++
 shumate/shumate-map.c             | 21 +++++++++++----------
 shumate/shumate-marker.c          |  9 ++++-----
 shumate/shumate-simple-map.c      | 10 ++++++++++
 shumate/shumate-tile-downloader.c |  9 +++++++++
 shumate/shumate-vector-renderer.c |  6 ++++++
 shumate/shumate-viewport.c        |  5 ++++-
 8 files changed, 52 insertions(+), 16 deletions(-)
---
diff --git a/shumate/shumate-data-source.c b/shumate/shumate-data-source.c
index 35b859c..99abef2 100644
--- a/shumate/shumate-data-source.c
+++ b/shumate/shumate-data-source.c
@@ -17,6 +17,12 @@
 
 #include "shumate-data-source.h"
 
+/**
+ * ShumateDataSource:
+ *
+ * The base class used to retrieve tiles as [class@GLib.Bytes].
+ */
+
 G_DEFINE_TYPE (ShumateDataSource, shumate_data_source, G_TYPE_OBJECT)
 
 
diff --git a/shumate/shumate-map-layer.c b/shumate/shumate-map-layer.c
index b88c813..7d906b1 100644
--- a/shumate/shumate-map-layer.c
+++ b/shumate/shumate-map-layer.c
@@ -23,6 +23,8 @@
 /**
  * ShumateMapLayer:
  *
+ * A [class@Shumate.Layer] implementation that fetches tiles from a [class@Shumate.MapSource]
+ * and draws them as a grid.
  */
 
 struct _ShumateMapLayer
diff --git a/shumate/shumate-map.c b/shumate/shumate-map.c
index 7f314ff..7e50d92 100644
--- a/shumate/shumate-map.c
+++ b/shumate/shumate-map.c
@@ -24,18 +24,19 @@
 /**
  * ShumateMap:
  *
- * A [class@Gtk.Widget] to display maps. It supports two modes of scrolling:
+ * The Map widget is a [class@Gtk.Widget] that show and allows interaction with
+ * the user.
  *
- * - 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.
+ * This is the base widget and doesn't have advanced features. You can check the
+ * [class@Shumate.SimpleMap] for a ready-to-use widget.
  *
- * The maps are downloaded from Internet from open maps sources (like
- * [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.
+ * By default, a [class@Shumate.ViewPort] is created and can be accessed with
+ * [method Shumate Map.get_viewport].
+ *
+ * Unless created with [ctor Shumate Map.new_simple], the widget doesn't hold any
+ * layer and won't show anything. A [class@Shumate.Layer] can be added or removed
+ * using the [method Shumate Map.add_layer] or [method Shumate Map.remove_layer]
+ * methods.
  */
 
 #include "shumate-map.h"
diff --git a/shumate/shumate-marker.c b/shumate/shumate-marker.c
index 6d563c0..fb48155 100644
--- a/shumate/shumate-marker.c
+++ b/shumate/shumate-marker.c
@@ -29,8 +29,10 @@
  * 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.
+ * This is a base class of all markers. A typical usage of a marker is for
+ * instance to add a [class@Gtk.Image] with a pin image and add the
+ * [class@Gtk.GestureClick] controller to listen to click events and show
+ * a [class@Gtk.Popover] with the description of the marker.
  */
 
 #include "shumate-marker.h"
@@ -42,10 +44,7 @@
 
 #include <glib.h>
 #include <glib-object.h>
-#include <gdk/gdk.h>
 #include <gtk/gtk.h>
-#include <cairo.h>
-#include <math.h>
 
 enum
 {
diff --git a/shumate/shumate-simple-map.c b/shumate/shumate-simple-map.c
index 568c126..e0f7a7c 100644
--- a/shumate/shumate-simple-map.c
+++ b/shumate/shumate-simple-map.c
@@ -19,6 +19,16 @@
 #include "shumate-map.h"
 #include "shumate-map-layer.h"
 
+/**
+ * ShumateSimpleMap:
+ *
+ * A ready-to-use map [class@Gtk.Widget].If you want to use your own implementation,
+ * you can look at the [class Shumate Map] widget.
+ *
+ * The simple map contains a zoom widget, a [class@Shumate.License] at the bottom,
+ * a [class@Shumate.Scale] and a [class@Shumate.Compass].
+ */
+
 struct _ShumateSimpleMap
 {
   GtkWidget parent_instance;
diff --git a/shumate/shumate-tile-downloader.c b/shumate/shumate-tile-downloader.c
index aef673f..d2a494f 100644
--- a/shumate/shumate-tile-downloader.c
+++ b/shumate/shumate-tile-downloader.c
@@ -20,6 +20,15 @@
 #include "shumate-file-cache.h"
 #include "shumate-user-agent.h"
 
+/**
+ * ShumateTileDownloader:
+ *
+ * A [class@Shumate.DataSource] that asynchronously downloads tiles from an online
+ * service using a given template.
+ *
+ * It contains an internal [class@Shumate.FileCache] to cache the tiles on the system.
+ */
+
 struct _ShumateTileDownloader
 {
   ShumateDataSource parent_instance;
diff --git a/shumate/shumate-vector-renderer.c b/shumate/shumate-vector-renderer.c
index 4384604..3dd4524 100644
--- a/shumate/shumate-vector-renderer.c
+++ b/shumate/shumate-vector-renderer.c
@@ -18,6 +18,12 @@
 #include "shumate-vector-renderer.h"
 #include "shumate-tile-downloader.h"
 
+/**
+ * ShumateVectorRenderer:
+ *
+ * A [class@Shumate.MapSource] that renders tiles from a given data source.
+ */
+
 #ifdef SHUMATE_HAS_VECTOR_RENDERER
 #include <json-glib/json-glib.h>
 #include <cairo/cairo.h>
diff --git a/shumate/shumate-viewport.c b/shumate/shumate-viewport.c
index ab7e63e..540371f 100644
--- a/shumate/shumate-viewport.c
+++ b/shumate/shumate-viewport.c
@@ -30,7 +30,10 @@
 /**
  * ShumateViewport:
  *
- * The object holding the coordinate and zoom-level state of the current view.
+ * The object holding the coordinate, zoom-level, and rotation state of the current view.
+ *
+ * As the object implements [iface@Shumate.Location], the latitude and longitude are
+ * accessible via the interface methods.
  */
 
 struct _ShumateViewport