Verified Commit c1daa615 authored by James Westman's avatar James Westman
Browse files

docs: Update map source docs

Part of #15.
parent b3cac32c
Pipeline #266776 passed with stage
in 3 minutes and 29 seconds
......@@ -22,9 +22,19 @@
* SECTION:shumate-file-cache
* @short_description: Stores and loads cached tiles from the file system
*
* #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.
* #ShumateFileCache caches tile data in the local cache directory so it
* doesn't have to be downloaded many times.
*
* Most applications don't need to use #ShumateFileCache directly, since
* #ShumateNetworkTileSource uses it automatically. However, custom map sources
* may find it useful.
*/
/**
* ShumateFileCacheError:
* @SHUMATE_FILE_CACHE_ERROR_DATABASE: An error occurred while accessing the tile database.
*
* Error codes for errors specific to #ShumateFileCache.
*/
#define DEBUG_FLAG SHUMATE_DEBUG_CACHE
......@@ -582,7 +592,8 @@ purge_cache (GTask *task, gpointer source_object, gpointer task_data, GCancellab
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
*
* Purge the cache from the less popular tiles until cache's size limit is reached.
* Purges the cache from the less popular tiles until cache's size limit is
* reached. This is done in a separate thread to avoid causing lag.
*/
void
shumate_file_cache_purge_async (ShumateFileCache *self,
......@@ -621,11 +632,14 @@ static void on_file_loaded (GObject *object, GAsyncResult *res, gpointer user_da
/**
* shumate_file_cache_retrieve_file_async:
* @self: a #ShumateFileCache
* @tile: a #ShumateTile
* @cancellable: (nullable): a #GCancellable
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
*
* Retrieves a tile from the cache, if it exists.
* Retrieves the tile data for the given tile, if available. If the data is
* not available, an error is set; use shumate_file_cache_check_validity()
* to make sure the data is available before trying to retrieve it.
*/
void
shumate_file_cache_retrieve_file_async (ShumateFileCache *self,
......@@ -760,6 +774,13 @@ static void store_tile_on_file_written (GFile *file,
* @cancellable: (nullable): a #GCancellable
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
*
* Stores tile data in the cache.
*
* The @etag is used to avoid downloading old, but still up-to-date tiles from
* web servers. shumate_file_cache_check_validity() will return this ETag even
* if the data is old so that map sources can send it in the If-None-Match
* HTTP header.
*/
void
shumate_file_cache_store_tile_async (ShumateFileCache *self,
......@@ -864,8 +885,8 @@ store_tile_on_file_written (GFile *file,
*/
gboolean
shumate_file_cache_store_tile_finish (ShumateFileCache *self,
GAsyncResult *result,
GError **error)
GAsyncResult *result,
GError **error)
{
g_return_val_if_fail (SHUMATE_IS_FILE_CACHE (self), FALSE);
g_return_val_if_fail (G_IS_TASK (result), FALSE);
......@@ -878,7 +899,7 @@ shumate_file_cache_store_tile_finish (ShumateFileCache *self,
* shumate_file_cache_check_validity_async:
* @self: a #ShumateFileCache
* @tile: a #ShumateTile
* @etag_out: (out) (transfer full): return location for the data's ETag
* @etag_out: (out)(allow-none)(nullable)(transfer full): return location for the data's ETag
*
* Checks whether the cache has valid, recent data for the given tile's
* location.
......
......@@ -21,35 +21,13 @@
* SECTION:shumate-map-source
* @short_description: A base class for map sources
*
* #ShumateTile objects come from map sources which are represented by
* #ShumateMapSource. This is should be considered an abstract
* type as it does nothing of interest.
*
* When loading new tiles, #ShumateView calls shumate_map_source_fill_tile()
* on the current #ShumateMapSource passing it a #ShumateTile to be filled
* with the image.
*
* Apart from being a base class of all map sources, #ShumateMapSource
* also supports cooperation of multiple map sources by arranging them into
* chains. Every map source has the #ShumateMapSource:next-source property
* that determines the next map source in the chain. When a function of
* a #ShumateMapSource object is invoked, the map source may decide to
* delegate the work to the next map source in the chain by invoking the
* same function on it.
* To understand the concept of chains, consider for instance a chain
* consisting of #ShumateFileCache whose next source is
* #ShumateNetworkTileSource whose next source is an error tile source
* created with shumate_map_source_factory_create_error_source ().
* When shumate_map_source_fill_tile() is called on the first object of the
* chain, #ShumateFileCache, the cache checks whether it contains the
* requested tile in its database. If it does, it returns the tile; otherwise,
* it calls shumate_map_source_fill_tile() on the next source in the chain
* (#ShumateNetworkTileSource). The network tile source loads the tile
* from the network. When successful, it returns the tile; otherwise it requests
* the tile from the next source in the chain (error tile source).
* The error tile source always generates an error tile, no matter what
* its next source is.
* #ShumateMapSource is the abstract base type for map sources. It produces
* tile data, usually (but not necessarily) in an image format like PNG or
* JPEG, for each tile on the screen.
*
* The built-in #ShumateNetworkTileSource is the most common tile source and
* should cover the needs of most applications, but custom tile sources are
* also possible by creating a subclass of #ShumateMapSource.
*/
#include "shumate-map-source.h"
......@@ -449,6 +427,7 @@ shumate_map_source_get_meters_per_pixel (ShumateMapSource *map_source,
/**
* shumate_map_source_get_tile_async:
* @self: a #ShumateMapSource
* @tile: a #ShumateTile
* @cancellable: (nullable): a #GCancellable
* @callback: a #GAsyncReadyCallback to execute upon completion
* @user_data: closure data for @callback
......@@ -480,7 +459,7 @@ shumate_map_source_get_tile_async (ShumateMapSource *self,
* Gets the tile data from an operation started by
* shumate_map_source_get_tile_async().
*
* Returns:
* Returns: the tile data as a #GBytes, or %NULL if there was an error
*/
GBytes *
shumate_map_source_get_tile_finish (ShumateMapSource *self,
......
......@@ -18,7 +18,7 @@
*/
/**
* SECTION:shumate-memory-cache
* PRIVATE:shumate-memory-cache
* @short_description: Stores and loads cached tiles from the memory
*
* #ShumateMemoryCache is a cache that stores and retrieves tiles from the
......
......@@ -29,7 +29,14 @@
*
* Some preconfigured network map sources are built-in this library,
* see #ShumateMapSourceFactory.
*/
/**
* ShumateNetworkError:
* @SHUMATE_NETWORK_ERROR_OFFLINE: Tiles may not be fetched because the tile source is marked as offline.
* @SHUMATE_NETWORK_ERROR_BAD_RESPONSE: A network error occurred, or the server sent a non-successful HTTP response.
*
* Error codes for errors specific to #ShumateNetworkTileSource.
*/
#include "config.h"
......
Markdown is supported
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