Initial libosrm API docs

include/engine/api/base_parameters.hpp

@@ -43,6 +43,22 @@ namespace engine
 {
 namespace api
 {
+
+/**
+ * General parameters for OSRM service queries.
+ *
+ * Holds member attributes:
+ *  - coordinates: for specifying location(s) to services
+ *  - hints: hint for the service to derive the position(s) in the road network more efficiently,
+ *           optional per coordinate
+ *  - radiuses: limits the search for segments in the road network to given radius(es) in meter,
+ *              optional per coordinate
+ *  - bearings: limits the search for segments in the road network to given bearing(s) in degree
+ *              towards true north in clockwise direction, optional per coordinate
+ *
+ * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters,
+ *      NearestParameters, TripParameters, MatchParameters and TileParameters
+ */
 struct BaseParameters
 {
     std::vector<util::Coordinate> coordinates;

include/engine/api/match_parameters.hpp

@@ -39,6 +39,15 @@ namespace engine
 namespace api
 {
 
+/**
+ * Parameters specific to the OSRM Match service.
+ *
+ * Holds member attributes:
+ *  - timestamps: timestamp(s) for the corresponding input coordinate(s)
+ *
+ * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters,
+ *      NearestParameters, TripParameters, MatchParameters and TileParameters
+ */
 struct MatchParameters : public RouteParameters
 {
     MatchParameters()

include/engine/api/nearest_parameters.hpp

@@ -37,6 +37,15 @@ namespace engine
 namespace api
 {
 
+/**
+ * Parameters specific to the OSRM Nearest service.
+ *
+ * Holds member attributes:
+ *  - number of results: number of nearest segments that should be returned
+ *
+ * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters,
+ *      NearestParameters, TripParameters, MatchParameters and TileParameters
+ */
 struct NearestParameters : public BaseParameters
 {
     unsigned number_of_results = 1;

include/engine/api/route_parameters.hpp

@@ -39,6 +39,20 @@ namespace engine
 namespace api
 {
 
+/**
+ * Parameters specific to the OSRM Route service.
+ *
+ * Holds member attributes:
+ *  - steps: return route step for each route leg
+ *  - alternatives: tries to find alternative routes
+ *  - geometries: route geometry encoded in Polyline or GeoJSON
+ *  - overview: adds overview geometry either Full, Simplified (according to highest zoom level) or
+ *              False (not at all)
+ *  - uturns: enable or disable uturns (disabled by default)
+ *
+ * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters,
+ *      NearestParameters, TripParameters, MatchParameters and TileParameters
+ */
 struct RouteParameters : public BaseParameters
 {
     enum class GeometriesType
@@ -73,10 +87,7 @@ struct RouteParameters : public BaseParameters
     OverviewType overview = OverviewType::Simplified;
     boost::optional<bool> uturns;
 
-    bool IsValid() const
+    bool IsValid() const { return coordinates.size() >= 2 && BaseParameters::IsValid(); }
-    {
-        return coordinates.size() >= 2 && BaseParameters::IsValid();
-    }
 };
 }
 }

include/engine/api/table_parameters.hpp

@@ -43,6 +43,18 @@ namespace engine
 namespace api
 {
 
+/**
+ * Parameters specific to the OSRM Table service.
+ *
+ * Holds member attributes:
+ *  - sources: indices into coordinates indicating sources for the Table service, no sources means
+ *             use all coordinates as sources
+ *  - destinations: indices into coordinates indicating destinations for the Table service, no
+ *                  destinations means use all coordinates as destinations
+ *
+ * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters,
+ *      NearestParameters, TripParameters, MatchParameters and TileParameters
+ */
 struct TableParameters : public BaseParameters
 {
     std::vector<std::size_t> sources;

include/engine/api/tile_parameters.hpp

@@ -37,6 +37,21 @@ namespace engine
 namespace api
 {
 
+/**
+ * Parameters specific to the OSRM Tile service.
+ *
+ * Holds member attributes:
+ *  - x: the x location for the tile
+ *  - y: the y location for the tile
+ *  - z: the zoom level for the tile
+ *
+ * The parameters x,y and z have to conform to the Slippy Map Tilenames specification:
+ *  - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Zoom_levels
+ *  - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#X_and_Y
+ *
+ * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters,
+ *      NearestParameters, TripParameters, MatchParameters and TileParameters
+ */
 struct TileParameters final
 {
     unsigned x;

include/engine/api/trip_parameters.hpp

@@ -39,6 +39,12 @@ namespace engine
 namespace api
 {
 
+/**
+ * Parameters specific to the OSRM Trip service.
+ *
+ * \see OSRM, Coordinate, Hint, Bearing, RouteParame, RouteParameters, TableParameters,
+ *      NearestParameters, TripParameters, MatchParameters and TileParameters
+ */
 struct TripParameters : public RouteParameters
 {
     // bool IsValid() const; Falls back to base class

include/engine/engine_config.hpp

@@ -40,7 +40,23 @@ namespace osrm
 namespace engine
 {
 
-struct EngineConfig
+/**
+ * Configures an OSRM instance.
+ *
+ * You can customize the storage OSRM uses for auxiliary files specifying a storage config.
+ *
+ * You can further set service constraints.
+ * These are the maximum number of allowed locations (-1 for unlimited) for the services:
+ *  - Trip
+ *  - Route
+ *  - Table
+ *  - Match
+ *
+ * In addition, shared memory can be used for datasets loaded with osrm-datastore.
+ *
+ * \see OSRM, StorageConfig
+ */
+struct EngineConfig final
 {
     bool IsValid() const;
 

include/engine/status.hpp

@@ -33,6 +33,10 @@ namespace osrm
 namespace engine
 {
 
+/**
+ * Status for indicating query success or failure.
+ * \see OSRM
+ */
 enum class Status
 {
     Ok,

include/osrm/osrm.hpp

@@ -45,20 +45,89 @@ using engine::api::TripParameters;
 using engine::api::MatchParameters;
 using engine::api::TileParameters;
 
+/**
+ * Represents a Open Source Routing Machine with access to its services.
+ *
+ * This represents an Open Source Routing Machine (OSRM) instance, with the services:
+ *
+ *  - Route: shortest path queries for coordinates
+ *  - Table: distance tables for coordinates
+ *  - Nearest: nearest street segment for coordinate
+ *  - Trip: shortest round trip between coordinates
+ *  - Match: snaps noisy coordinate traces to the road network
+ *  - Tile: vector tiles with internal graph representation
+ *
+ *  All services take service-specific parameters, fill a JSON object, and return a status code.
+ */
 class OSRM final
 {
   public:
+    /**
+     * Constructs an OSRM instance with user-configurable settings.
+     *
+     * \param config The user-provided OSRM configuration.
+     * \see EngineConfig
+     */
     explicit OSRM(EngineConfig &config);
+
     ~OSRM();
 
+    // Moveable but not copyable
     OSRM(OSRM &&) noexcept;
     OSRM &operator=(OSRM &&) noexcept;
 
+    /**
+     * Shortest path queries for coordinates.
+     *
+     * \param parameters route query specific parameters
+     * \return Status indicating success for the query or failure
+     * \see Status, RouteParameters and json::Object
+     */
     Status Route(const RouteParameters &parameters, json::Object &result);
+
+    /**
+     * Distance tables for coordinates.
+     *
+     * \param parameters table query specific parameters
+     * \return Status indicating success for the query or failure
+     * \see Status, TableParameters and json::Object
+     */
     Status Table(const TableParameters &parameters, json::Object &result);
+
+    /**
+     * Nearest street segment for coordinate.
+     *
+     * \param parameters nearest query specific parameters
+     * \return Status indicating success for the query or failure
+     * \see Status, NearestParameters and json::Object
+     */
     Status Nearest(const NearestParameters &parameters, json::Object &result);
+
+    /**
+     * Trip: shortest round trip between coordinates.
+     *
+     * \param parameters trip query specific parameters
+     * \return Status indicating success for the query or failure
+     * \see Status, TripParameters and json::Object
+     */
     Status Trip(const TripParameters &parameters, json::Object &result);
+
+    /**
+     * Match: snaps noisy coordinate traces to the road network
+     *
+     * \param parameters match query specific parameters
+     * \return Status indicating success for the query or failure
+     * \see Status, MatchParameters and json::Object
+     */
     Status Match(const MatchParameters &parameters, json::Object &result);
+
+    /**
+     * Tile: vector tiles with internal graph representation
+     *
+     * \param parameters tile query specific parameters
+     * \return Status indicating success for the query or failure
+     * \see Status, TileParameters and json::Object
+     */
     Status Tile(const TileParameters &parameters, std::string &result);
 
   private:

include/storage/storage_config.hpp

@@ -7,9 +7,21 @@ namespace osrm
 {
 namespace storage
 {
-struct StorageConfig
+
+/**
+ * Configures OSRM's file storage paths.
+ *
+ * \see OSRM, EngineConfig
+ */
+struct StorageConfig final
 {
     StorageConfig() = default;
+
+    /**
+     * Constructs a storage configuration setting paths based on a base path.
+     *
+     * \param base The base path (e.g. france.pbf.osrm) to derive auxiliary file suffixes from.
+     */
     StorageConfig(const boost::filesystem::path &base);
     bool IsValid() const;
 

include/util/coordinate.hpp

@@ -50,6 +50,13 @@ OSRM_STRONG_TYPEDEF(int32_t, FixedLongitude)
 OSRM_STRONG_TYPEDEF(double, FloatLatitude)
 OSRM_STRONG_TYPEDEF(double, FloatLongitude)
 
+/**
+ * Converts a typed latitude from floating to fixed representation.
+ *
+ * \param floating typed latitude in floating representation.
+ * \return typed latitude in fixed representation
+ * \see Coordinate, toFloating
+ */
 inline FixedLatitude toFixed(const FloatLatitude floating)
 {
     const auto latitude = static_cast<double>(floating);
@@ -57,6 +64,13 @@ inline FixedLatitude toFixed(const FloatLatitude floating)
     return FixedLatitude(fixed);
 }
 
+/**
+ * Converts a typed longitude from floating to fixed representation.
+ *
+ * \param floating typed longitude in floating representation.
+ * \return typed latitude in fixed representation
+ * \see Coordinate, toFloating
+ */
 inline FixedLongitude toFixed(const FloatLongitude floating)
 {
     const auto longitude = static_cast<double>(floating);
@@ -64,6 +78,13 @@ inline FixedLongitude toFixed(const FloatLongitude floating)
     return FixedLongitude(fixed);
 }
 
+/**
+ * Converts a typed latitude from fixed to floating representation.
+ *
+ * \param fixed typed latitude in fixed representation.
+ * \return typed latitude in floating representation
+ * \see Coordinate, toFixed
+ */
 inline FloatLatitude toFloating(const FixedLatitude fixed)
 {
     const auto latitude = static_cast<std::int32_t>(fixed);
@@ -71,6 +92,13 @@ inline FloatLatitude toFloating(const FixedLatitude fixed)
     return FloatLatitude(floating);
 }
 
+/**
+ * Converts a typed longitude from fixed to floating representation.
+ *
+ * \param fixed typed longitude in fixed representation.
+ * \return typed longitude in floating representation
+ * \see Coordinate, toFixed
+ */
 inline FloatLongitude toFloating(const FixedLongitude fixed)
 {
     const auto longitude = static_cast<std::int32_t>(fixed);
@@ -78,9 +106,22 @@ inline FloatLongitude toFloating(const FixedLongitude fixed)
     return FloatLongitude(floating);
 }
 
+// fwd. decl.
 struct FloatCoordinate;
 
-// Coordinate encoded as longitude, latitude
+/**
+ * Represents a coordinate based on longitude and latitude in fixed representation.
+ *
+ * To prevent accidental longitude and latitude flips, we provide typed longitude and latitude
+ * wrappers. You can cast these wrappers back to their underlying representation or convert them
+ * from one representation to the other.
+ *
+ * The two representation we provide are:
+ *  - Fixed point
+ *  - Floating point
+ *
+ * \see FloatCoordinate, toFixed, toFloating
+ */
 struct Coordinate
 {
     FixedLongitude lon;
@@ -107,7 +148,19 @@ struct Coordinate
     friend std::ostream &operator<<(std::ostream &out, const Coordinate coordinate);
 };
 
-// Coordinate encoded as longitude, latitude
+/**
+ * Represents a coordinate based on longitude and latitude in floating representation.
+ *
+ * To prevent accidental longitude and latitude flips, we provide typed longitude and latitude
+ * wrappers. You can cast these wrappers back to their underlying representation or convert them
+ * from one representation to the other.
+ *
+ * The two representation we provide are:
+ *  - Fixed point
+ *  - Floating point
+ *
+ * \see Coordinate, toFixed, toFloating
+ */
 struct FloatCoordinate
 {
     FloatLongitude lon;

include/util/json_container.hpp

@@ -44,12 +44,35 @@ namespace osrm
 namespace util
 {
 
+/**
+ * JSON types representing OSRM responses.
+ *
+ * The json::Value type represents the basic sum-type, implemented as a variant.
+ *
+ * There are two ways for destructuring such types:
+ *  - Either provide a visitor and use the apply_visitor function or
+ *  - use the get function and explicitely specify the type
+ *
+ * See the following documentations on variants:
+ *  - https://github.com/mapbox/variant
+ *  - http://www.boost.org/doc/libs/1_55_0/doc/html/variant.html
+ *
+ * And take a look at the example we provide.
+ *
+ * \see OSRM
+ */
 namespace json
 {
 
+// fwd. decls.
 struct Object;
 struct Array;
 
+/**
+ * Typed string wrapper.
+ *
+ * Unwrap the type via its value member attribute.
+ */
 struct String
 {
     String() = default;
@@ -58,6 +81,11 @@ struct String
     std::string value;
 };
 
+/**
+ * Typed floating point number.
+ *
+ * Unwrap the type via its value member attribute.
+ */
 struct Number
 {
     Number() = default;
@@ -65,18 +93,32 @@ struct Number
     double value;
 };
 
+/**
+ * Typed True.
+ */
 struct True
 {
 };
 
+/**
+ * Typed False.
+ */
 struct False
 {
 };
 
+/**
+ * Typed Null.
+ */
 struct Null
 {
 };
 
+/**
+ * Typed Value sum-type implemented as a variant able to represent tree-like JSON structures.
+ *
+ * Dispatch on its type by either by using apply_visitor or its get function.
+ */
 using Value = mapbox::util::variant<String,
                                     Number,
                                     mapbox::util::recursive_wrapper<Object>,
@@ -85,17 +127,27 @@ using Value = mapbox::util::variant<String,
                                     False,
                                     Null>;
 
+/**
+ * Typed Object.
+ *
+ * Unwrap the key-value pairs holding type via its values member attribute.
+ */
 struct Object
 {
     std::unordered_map<std::string, Value> values;
 };
 
+/**
+ * Typed Array.
+ *
+ * Unwrap the Value holding type via its values member attribute.
+ */
 struct Array
 {
     std::vector<Value> values;
 };
 
-} // namespace JSON
+} // namespace json
 } // namespace util
 } // namespace osrm