Refactor:core:Documentation update (#1095)

9 files changed, 109 insertions, 55 deletions

diff --git a/navit/item.h b/navit/item.h
index 26c83cd72..d3e222196 100644
--- a/navit/item.h
+++ b/navit/item.h
@@ -95,7 +95,22 @@ struct item_id {
 #define ITEM_ID_ARGS(x) (x).id_hi,(x).id_lo
 
 /**
- * Represents an object on a map, such as a POI, a building, a way or a boundary.
+ * @brief Represents an object on a map.
+ *
+ * An item holds the data for an individual item on a map, including its coordinates and various attributes. The item
+ * type specifies what the map item refers to, such as a POI, a building, a way or a boundary. There are also special
+ * item types used internally, such as the various kinds of turn instructions. Item types are internally represented as
+ * numbers.
+ *
+ * Outside map implementations, items are generally retrieved from map rectangles, and their methods are implemented by
+ * the respective map driver. Items retrieved from a map rectangle are generally short-lived: a previously retrieved
+ * item should be considered invalid when a new item is retrieved from the same map rectangle, or after its map
+ * rectangle has been destroyed. After that, functions may segfault or return invalid data, and even the item itself
+ * may have been deallocated.
+ *
+ * Actual behavior may differ between map implementations, but do not rely on any behavior not covered by the above
+ * interface contract. Exceptions apply, of course, for code that is limited to working with items from one particular
+ * map (typically inside a map implementation).
  */
 struct item {
     enum item_type type; /**< Type of the item.*/
@@ -110,6 +125,12 @@ extern struct item_range {
     enum item_type min,max;
 } item_range_all;
 
+/**
+ * @brief An item indicating that the map driver is busy fetching more items.
+ *
+ * This is a “magic” item which may be returned by one of the query methods of a map driver. Receiving this item means
+ * that the map driver is currently busy fetching more items, and they can be retrieved at a later point in time.
+ */
 extern struct item busy_item;
 
 /* prototypes */
diff --git a/navit/map.c b/navit/map.c
index c8cddbcc2..e3034d429 100644
--- a/navit/map.c
+++ b/navit/map.c
@@ -52,11 +52,6 @@
 #include "country.h"
 #include "xmlconfig.h"
 
-/**
- * @brief Holds information about a map
- *
- * This structure holds information about a map.
- */
 struct map {
     NAVIT_OBJECT
     struct map_methods meth;			/**< Structure with pointers to the map plugin's functions */
@@ -64,11 +59,6 @@ struct map {
     struct callback_list *attr_cbl;		/**< List of callbacks that are called when attributes change */
 };
 
-/**
- * @brief Describes a rectangular extract of a map
- *
- * This structure describes a rectangular extract of a map.
- */
 struct map_rect {
     struct map *m;				/**< The map this extract is from */
     struct map_rect_priv *priv; /**< Private data of this map rect, only known to the map plugin */
@@ -375,12 +365,6 @@ void map_rect_destroy(struct map_rect *mr) {
     }
 }
 
-/**
- * @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 *m;
     struct attr search_attr;
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);
diff --git a/navit/map/csv/csv.h b/navit/map/csv/csv.h
index c32be1eff..c48458c82 100644
--- a/navit/map/csv/csv.h
+++ b/navit/map/csv/csv.h
@@ -27,19 +27,17 @@
 
 struct map_priv {
 	int id;
-	struct quadtree_node* tree_root;
+	struct quadtree_node* tree_root; /**< Root of the quadtree from which items can be retrieved by their coordinates */
 	int flags;
-	GHashTable*qitem_hash;
-	char* filename;
-	/*need to write map file on exit*/
-	int dirty;
-	int attr_cnt;
-	enum attr_type *attr_types;
-	int next_item_idx;
-	enum item_type item_type;
-	/*list of quadtree items that have no coord set yet ()*/
-	GList* new_items;
-	char *charset;
+	GHashTable*qitem_hash;           /**< Hash table to retrieve items by their ID */
+	char* filename;                  /**< Name of the file in which the map is stored */
+	int dirty;                       /**< Need to write map file on exit */
+	int attr_cnt;                    /**< Number of elements in `attr_types` */
+	enum attr_type *attr_types;      /**< Array of attribute types supported by this map */
+	int next_item_idx;               /**< Zero-based index (`id_lo`) for the next item to be added */
+	enum item_type item_type;        /**< Item type stored in this map */
+	GList* new_items;                /**< List of quadtree items that have no coord set yet */
+	char *charset;                   /**< Identifier for the character set of this map */
 };
 
 struct map_rect_priv {
diff --git a/navit/mapset.c b/navit/mapset.c
index 94f1f42be..409437e51 100644
--- a/navit/mapset.c
+++ b/navit/mapset.c
@@ -36,11 +36,6 @@
 #include "map.h"
 #include "xmlconfig.h"
 
-/**
- * @brief A mapset
- *
- * This structure holds a complete mapset
- */
 struct mapset {
     NAVIT_OBJECT
     GList *maps; /**< Linked list of all the maps in the mapset */
diff --git a/navit/mapset.h b/navit/mapset.h
index df6c0d0a7..6aca2afdc 100644
--- a/navit/mapset.h
+++ b/navit/mapset.h
@@ -30,7 +30,15 @@ struct attr;
 struct attr_iter;
 struct item;
 struct map;
+
+/**
+ * @brief A mapset.
+ *
+ * A mapset is a collection of (one or more) maps. This allows you to combine data from multiple maps, e.g. one map
+ * with the road network and another with special POIs.
+ */
 struct mapset;
+
 struct mapset_handle;
 struct mapset_search;
 struct mapset *mapset_new(struct attr *parent, struct attr **attrs);
diff --git a/navit/route.c b/navit/route.c
index 4c85e3fe9..b9fa9667f 100644
--- a/navit/route.c
+++ b/navit/route.c
@@ -2300,10 +2300,13 @@ static void route_graph_set_traffic_distortion(struct route_graph *this, struct
 /**
  * @brief Adds a traffic distortion item to the route graph
  *
+ * If `update` is true, the end points of the traffic distortion will have their cost recalculated. Set this to true
+ * for a partial recalculation of an existing route, false when initially building the route graph.
+ *
  * @param this The route graph to add to
  * @param profile The vehicle profile to use for cost calculations
  * @param item The item to add, must be of {@code type_traffic_distortion}
- * @param update Whether to update the point (true for LPA*, false for Dijkstra)
+ * @param update Whether to update the end points
  */
 static void route_graph_add_traffic_distortion(struct route_graph *this, struct vehicleprofile *profile,
         struct item *item, int update) {
@@ -2700,10 +2703,8 @@ static int route_graph_is_path_computed(struct route_graph *this_) {
  * After recalculation, the route path is updated.
  *
  * The function uses a modified LPA* algorithm for recalculations. Most modifications were made for compatibility with
- * the algorithm used for the initial routing:
- * \li The `value` of a node represents the cost to reach the destination and thus decreases along the route
- * (eliminating the need for recalculations as the vehicle moves within the route graph)
- * \li The heuristic is always assumed to be zero (which would turn A* into Dijkstra, the basis of the main routing
+ * the old routing algorithm:
+ * \li The heuristic is always assumed to be zero (which would turn A* into Dijkstra, formerly the basis of the routing
  * algorithm, and makes our keys one-dimensional)
  * \li Currently, each pass evaluates all locally inconsistent points, leaving an empty heap at the end (though this
  * may change in the future).
diff --git a/navit/route_protected.h b/navit/route_protected.h
index 3ce6c4663..32d61e9bd 100644
--- a/navit/route_protected.h
+++ b/navit/route_protected.h
@@ -140,7 +140,9 @@ struct route_graph_segment {
  * each segment.
  */
 struct route_graph {
-	int busy;                                   /**< The graph is being built */
+	int busy;                                   /**< Route calculation is in progress: the graph is being built,
+	                                             *   flooded or the path is being built (a more detailed status can be
+	                                             *   obtained from the route’s status attribute) */
 	struct map_selection *sel;                  /**< The rectangle selection for the graph */
 	struct mapset_handle *h;                    /**< Handle to the mapset */
 	struct map *m;                              /**< Pointer to the currently active map */
@@ -150,7 +152,7 @@ struct route_graph {
 	struct callback *done_cb;                   /**< Callback when graph is done */
 	struct event_idle *idle_ev;                 /**< The pointer to the idle event */
 	struct route_graph_segment *route_segments; /**< Pointer to the first route_graph_segment in the linked list of all segments */
-	struct route_graph_segment *avoid_seg;
+	struct route_graph_segment *avoid_seg;      /**< Segment to which a turnaround penalty (if active) applies */
 	struct fibheap *heap;                       /**< Priority queue for points to be expanded */
 #define HASH_SIZE 8192
 	struct route_graph_point *hash[HASH_SIZE];  /**< A hashtable containing all route_graph_points in this graph */
diff --git a/navit/track.c b/navit/track.c
index 70b89c6fc..3330c929c 100644
--- a/navit/track.c
+++ b/navit/track.c
@@ -83,12 +83,12 @@ struct cdf_data {
 
 struct tracking {
     NAVIT_OBJECT
-    struct callback_list *callback_list;
-    struct mapset *ms;
-    struct route *rt;
-    struct map *map;
-    struct vehicle *vehicle;
-    struct vehicleprofile *vehicleprofile;
+    struct callback_list *callback_list;     /**< Callbacks which will be called whenever the position changes */
+    struct mapset *ms;                       /**< The mapset */
+    struct route *rt;                        /**< The route */
+    struct map *map;                         /**< The tracking map which holds our past movements */
+    struct vehicle *vehicle;                 /**< The vehicle from which we are obtaining location data */
+    struct vehicleprofile *vehicleprofile;   /**< The current vehicle profile */
     struct coord last_updated;
     struct tracking_line *lines;
     struct tracking_line *curr_line;
@@ -98,16 +98,16 @@ struct tracking {
     struct coord last[2], last_in, last_out;
     struct cdf_data cdf;
     struct attr *attr;
-    int valid;
+    int valid;                               /**< Whether we have valid location data */
     int time;
     double direction, direction_matched;
-    double speed;
+    double speed;                            /**< Current speed */
     int coord_geo_valid;
     struct coord_geo coord_geo;
     enum projection pro;
     int street_direction;
     int no_gps;
-    int tunnel;
+    int tunnel;                              /**< Whether we are in a tunnel */
     int angle_pref;
     int connected_pref;
     int nostop_pref;