[libshumate] docs: Update FileCache and NetworkTileSource docs

[Marcus Lundblad <mlundblad src gnome org>]

commit 791edf97da47c18d4f7a488f17297cb772506535
Author: James Westman <james jwestman net>
Date:   Fri Mar 19 10:07:46 2021 -0500

    docs: Update FileCache and NetworkTileSource docs

 shumate/shumate-file-cache.c          | 18 ++++++++++++++----
 shumate/shumate-network-tile-source.c |  8 +++-----
 2 files changed, 17 insertions(+), 9 deletions(-)
---
diff --git a/shumate/shumate-file-cache.c b/shumate/shumate-file-cache.c
index a54570b..20acaf0 100644
--- a/shumate/shumate-file-cache.c
+++ b/shumate/shumate-file-cache.c
@@ -20,11 +20,21 @@
 
 /**
  * SECTION:shumate-file-cache
- * @short_description: Stores and loads cached tiles from the file system
+ * @short_description: Caches tiles on the filesystem
  *
  * #ShumateFileCache is a cache that stores and retrieves tiles from the
- * file system. Tiles most frequently loaded gain in "popularity". This popularity
- * is taken into account when purging the cache.
+ * file system. It is mainly used by #ShumateNetworkTileSource, 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
+ * deleted.
+ *
+ * ## ETags
+ *
+ * The cache can optionally store an ETag string with each tile. This is
+ * useful to avoid redownloading old tiles that haven't changed (for example,
+ * using the HTTP If-None-Match header).
  */
 
 #define DEBUG_FLAG SHUMATE_DEBUG_CACHE
@@ -348,9 +358,9 @@ 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: an ID for the tileset to store/retrieve
  *
  * Constructor of #ShumateFileCache.
  *
diff --git a/shumate/shumate-network-tile-source.c b/shumate/shumate-network-tile-source.c
index 4fc4f8d..5356b52 100644
--- a/shumate/shumate-network-tile-source.c
+++ b/shumate/shumate-network-tile-source.c
@@ -22,14 +22,12 @@
  * SECTION:shumate-network-tile-source
  * @short_description: A map source that downloads tile data from a web server
  *
- * This class is specialized for map tiles that can be downloaded
- * from a web server.  This includes all web based map services such as
- * OpenStreetMap, Google Maps, Yahoo Maps and more.  This class contains
- * all mechanisms necessary to download tiles.
+ * #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.
  *
  * Some preconfigured network map sources are built-in this library,
  * see #ShumateMapSourceFactory.
- *
  */
 
 #include "config.h"