diff options
author | mvglasow <michael@vonglasow.com> | 2021-02-28 13:27:09 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-02-28 13:27:09 +0100 |
commit | 2146fcd9c9ce1560b725e481dc8b808dd425b1d2 (patch) | |
tree | 5a7b652cf17ae15208205a626d4daa58aeeb6c43 | |
parent | e90aa031b50b6d3031537b30fd9c559d43c516cf (diff) | |
download | navit-2146fcd9c9ce1560b725e481dc8b808dd425b1d2.tar.gz |
Refactor:core:Documentation update (#1095)
-rw-r--r-- | navit/item.h | 23 | ||||
-rw-r--r-- | navit/map.c | 16 | ||||
-rw-r--r-- | navit/map.h | 55 | ||||
-rw-r--r-- | navit/map/csv/csv.h | 22 | ||||
-rw-r--r-- | navit/mapset.c | 5 | ||||
-rw-r--r-- | navit/mapset.h | 8 | ||||
-rw-r--r-- | navit/route.c | 11 | ||||
-rw-r--r-- | navit/route_protected.h | 6 | ||||
-rw-r--r-- | navit/track.c | 18 |
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; |