1 files changed, 50 insertions, 5 deletions
diff --git a/navit/map.h b/navit/map.h
index 78521bccf..63fa889e3 100644
--- a/navit/map.h
+++ b/navit/map.h
@@ -47,12 +47,13 @@ struct attr;
 /**
  * @brief Used to select data from a map
  *
- * This struct is used to select data from a map. This one the one hand builds a
- * rectangle on the map and on the other hand selects an order for items of each
- * layer. Note that passing NULL instead of a pointer to such a struct often means
- * "get me everything".
+ * A map selection is a map query, used to select data from a map. It builds a coordinate rectangle on the map and
+ * selects a range of item types to query the map for.
  *
- * It's possible to link multiple selections in a linked list, see below.
+ * Multiple rectangular areas and/or non-contiguous ranges of item types can be specified by concatenating multiple map
+ * selections in a linked list.
+ *
+ * Note that passing NULL instead of a pointer to such a struct often means "get me everything".
  */
 struct map_selection {
 	struct map_selection *next;     /**< Linked-List pointer */
@@ -236,10 +237,54 @@ struct attr;
 struct attr_iter;
 struct callback;
 struct item;
+
+/**
+ * @brief Holds information about a map
+ *
+ * A map holds data used for screen display, search and routing. Maps can come in different forms, such as stored in
+ * files or created on the fly in memory. Flat-file maps typically hold the data commonly found in a road map, such as
+ * roads, land uses, buildings and POIs. In-memory maps are used internally for data which changes at runtime, such as
+ * information on the currently active route or traffic reports.
+ *
+ * To read data from a map (or add data if the map driver supports it), you need to obtain a map rectangle by calling
+ * the map’s `map_rect_new` method. By passing a map selection it is possible to restrict the items retrieved from the
+ * map to a certain region or to certain item types.
+ */
 struct map;
+
+/**
+ * @brief Implementation-specific map data.
+ *
+ * This struct is defined individually by each map driver and not ment to be accessed outside the map driver.
+ */
 struct map_priv;
+
+/**
+ * @brief Describes an extract of a map
+ *
+ * A map rectangle is the result of a map query. It can be obtained from the map by calling `map_rect_new` and passing
+ * a map selection. The resulting map rectangle can be queried for items. Contrary to its name, a map rectangle does
+ * not necessarily correspond to a rectangle: depending on the map selection it was created from, it can hold data from
+ * multiple rectangular areas (which may or may not overlap) or from the entire map.
+ *
+ * Map rectangles are not guaranteed to be thread-safe, i.e. a map rectangle should never be accessed by more than one
+ * thread without proper external synchronization. It is recommended that each thread obtain a separate map rectangle.
+ *
+ * Map implementations must ensure, however, that accesses to different map rectangles of the same map by different
+ * threads are properly synchronized. Most importantly, they must ensure that threads reading from one map rectangle
+ * receive consistent data while another thread is writing to another (which may also happen when reloading data from a
+ * stored map).
+ */
 struct map_rect;
+
+/**
+ * @brief Holds information about a search on a map
+ *
+ * This structure holds information about a search performed on a map. This can be
+ * used as "handle" to retrieve items from a search.
+ */
 struct map_search;
+
 struct map_selection;
 struct pcoord;
 struct map *map_new(struct attr *parent, struct attr **attrs);