diff --git a/.github/workflows/osrm-backend.yml b/.github/workflows/osrm-backend.yml index 37d200e0e6..7f12f3abbb 100644 --- a/.github/workflows/osrm-backend.yml +++ b/.github/workflows/osrm-backend.yml @@ -115,9 +115,11 @@ jobs: - name: Run checks run: | ./scripts/check_taginfo.py taginfo.json profiles/car.lua - ./scripts/format.sh && ./scripts/error_on_dirty.sh + # Check that code formatting is up to date + ./scripts/format.sh && ./scripts/error_on_dirty.sh "Run './scripts/format.sh' locally and commit the changes." node ./scripts/validate_changelog.js - npm run docs && ./scripts/error_on_dirty.sh + # Check that API documentation is up to date with JSDoc comments in node_osrm.cpp + npm run docs && ./scripts/error_on_dirty.sh "Run 'npm run docs' locally and commit the changes." npm audit --production docker-image-matrix: diff --git a/CHANGELOG.md b/CHANGELOG.md index dc49a28093..d6d0cfbed8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ - FIXED: Reduce MSVC compiler warnings by suppressing informational warnings while preserving bug-indicating warnings [#7253](https://github.com/Project-OSRM/osrm-backend/issues/7253) - Misc: - FIXED: Fix JSON rendering of large OSM IDs (avoids scientific notation) and handle NaN/Infinity gracefully [#7016](https://github.com/Project-OSRM/osrm-backend/issues/7016) + - FIXED: Replace removed --polyglot flag with JSDoc extraction script for documentation.js v14 [#7274](https://github.com/Project-OSRM/osrm-backend/issues/7274) - CHANGED: Add std::format compatibility layer with fallback to fmt::format [#7261](https://github.com/Project-OSRM/osrm-backend/pull/7261) - FIXED: Update node_osrm to C++20 to fix ABI mismatch with libosrm (was overlooked in #6877) [#7261](https://github.com/Project-OSRM/osrm-backend/pull/7261) - CHANGED: Update fmt library to version 11.2.0 [#7238](https://github.com/Project-OSRM/osrm-backend/issues/7238) diff --git a/docs/nodejs/api.md b/docs/nodejs/api.md index 0da19d063c..9fe57ab038 100644 --- a/docs/nodejs/api.md +++ b/docs/nodejs/api.md @@ -10,7 +10,7 @@ profiles (e.g. for setting speeds and determining road types to route on) in `no node_modules/osrm/lib/binding_napi_v8/osrm-extract data.osm.pbf -p node_modules/osrm/profiles/car.lua node_modules/osrm/lib/binding_napi_v8/osrm-contract data.osrm -Consult the [osrm-backend](https://github.com/Project-OSRM/osrm-backend) documentation for further details. +Consult the [osrm-backend][1] documentation for further details. Once you have a complete `network.osrm.*` dataset, you can calculate routes in javascript with this object. @@ -18,60 +18,62 @@ Once you have a complete `network.osrm.*` dataset, you can calculate routes in j var osrm = new OSRM('network.osrm'); ``` -**Parameters** - -- `options` **([Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** Options for creating an OSRM object or string to the `.osrm` file. (optional, default `{shared_memory:true}`) - - `options.algorithm` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** The algorithm to use for routing. Can be 'CH', or 'MLD'. Default is 'CH'. - Make sure you prepared the dataset with the correct toolchain. - - `options.shared_memory` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Connects to the persistent shared memory datastore. - This requires you to run `osrm-datastore` prior to creating an `OSRM` object. - - `options.dataset_name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Connects to the persistent shared memory datastore defined by `--dataset_name` option when running `osrm-datastore`. - This requires you to run `osrm-datastore --dataset_name` prior to creating an `OSRM` object. - - `options.memory_file` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** **DEPRECATED** - Old behaviour: Path to a file on disk to store the memory using mmap. Current behaviour: setting this value is the same as setting `mmap_memory: true`. - - `options.mmap_memory` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Map on-disk files to virtual memory addresses (mmap), rather than loading into RAM. - - `options.path` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** The path to the `.osrm` files. This is mutually exclusive with setting {options.shared_memory} to true. - - `options.disable_feature_dataset` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Disables a feature dataset from being loaded into memory if not needed. Options: `ROUTE_STEPS`, `ROUTE_GEOMETRY`. - - `options.max_locations_trip` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Max. locations supported in trip query (default: unlimited). - - `options.max_locations_viaroute` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Max. locations supported in viaroute query (default: unlimited). - - `options.max_locations_distance_table` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Max. locations supported in distance table query (default: unlimited). - - `options.max_locations_map_matching` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Max. locations supported in map-matching query (default: unlimited). - - `options.max_radius_map_matching` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Max. radius size supported in map matching query (default: 5). - - `options.max_results_nearest` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Max. results supported in nearest query (default: unlimited). - - `options.max_alternatives` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Max. number of alternatives supported in alternative routes query (default: 3). - - `options.default_radius` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Default radius for queries (default: unlimited). +### Parameters + +* `options` **([Object][2] | [String][3])** Options for creating an OSRM object or string to the `.osrm` file. (optional, default `{shared_memory:true}`) + + * `options.algorithm` **[String][3]?** The algorithm to use for routing. Can be 'CH', or 'MLD'. Default is 'CH'. + Make sure you prepared the dataset with the correct toolchain. + * `options.shared_memory` **[Boolean][4]?** Connects to the persistent shared memory datastore. + This requires you to run `osrm-datastore` prior to creating an `OSRM` object. + * `options.dataset_name` **[String][3]?** Connects to the persistent shared memory datastore defined by `--dataset_name` option when running `osrm-datastore`. + This requires you to run `osrm-datastore --dataset_name` prior to creating an `OSRM` object. + * `options.memory_file` **[String][3]?** **DEPRECATED** + Old behaviour: Path to a file on disk to store the memory using mmap. Current behaviour: setting this value is the same as setting `mmap_memory: true`. + * `options.mmap_memory` **[Boolean][4]?** Map on-disk files to virtual memory addresses (mmap), rather than loading into RAM. + * `options.path` **[String][3]?** The path to the `.osrm` files. This is mutually exclusive with setting {options.shared\_memory} to true. + * `options.disable_feature_dataset` **[Array][5]?** Disables a feature dataset from being loaded into memory if not needed. Options: `ROUTE_STEPS`, `ROUTE_GEOMETRY`. + * `options.max_locations_trip` **[Number][6]?** Max. locations supported in trip query (default: unlimited). + * `options.max_locations_viaroute` **[Number][6]?** Max. locations supported in viaroute query (default: unlimited). + * `options.max_locations_distance_table` **[Number][6]?** Max. locations supported in distance table query (default: unlimited). + * `options.max_locations_map_matching` **[Number][6]?** Max. locations supported in map-matching query (default: unlimited). + * `options.max_radius_map_matching` **[Number][6]?** Max. radius size supported in map matching query (default: 5). + * `options.max_results_nearest` **[Number][6]?** Max. results supported in nearest query (default: unlimited). + * `options.max_alternatives` **[Number][6]?** Max. number of alternatives supported in alternative routes query (default: 3). + * `options.default_radius` **[Number][6]?** Default radius for queries (default: unlimited). ### route Returns the fastest route between two or more coordinates while visiting the waypoints in order. -**Parameters** - -- `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object literal containing parameters for the route query. - - `options.coordinates` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. - - `options.bearings` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. - Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. - - `options.radiuses` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Limits the coordinate snapping to streets in the given radius in meters. Can be `null` (unlimited, default) or `double >= 0`. - - `options.hints` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Hints for the coordinate snapping. Array of base64 encoded strings. - - `options.exclude` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** List of classes to avoid, order does not matter. - - `options.generate_hints` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) - - `options.alternatives` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Search for alternative routes. (optional, default `false`) - - `options.alternatives` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Search for up to this many alternative routes. - _Please note that even if alternative routes are requested, a result cannot be guaranteed._ (optional, default `0`) - - `options.steps` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Return route steps for each route leg. (optional, default `false`) - - `options.annotations` **([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`) - - `options.geometries` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`) - - `options.overview` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Add overview geometry either `full`, `simplified` according to highest zoom level it could be displayed on, or not at all (`false`). (optional, default `simplified`) - - `options.continue_straight` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Forces the route to keep going straight at waypoints and don't do a uturn even if it would be faster. Default value depends on the profile. - - `options.approaches` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Restrict the direction on the road network at a waypoint, relative to the input coordinate. Can be `null` (unrestricted, default), `curb` or `opposite`. - `null`/`true`/`false` - - `options.waypoints` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Indices to coordinates to treat as waypoints. If not supplied, all coordinates are waypoints. Must include first and last coordinate index. - - `options.format` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Which output format to use, either `json`, or [`flatbuffers`](https://github.com/Project-OSRM/osrm-backend/tree/master/include/engine/api/flatbuffers). - - `options.snapping` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. - - `options.skip_waypoints` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Removes waypoints from the response. Waypoints are still calculated, but not serialized. Could be useful in case you are interested in some other part of response and do not want to transfer waste data. (optional, default `false`) -- `callback` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** - -**Examples** +#### Parameters + +* `options` **[Object][2]** Object literal containing parameters for the route query. + + * `options.coordinates` **[Array][5]?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. + * `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. + Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. + * `options.radiuses` **[Array][5]?** Limits the coordinate snapping to streets in the given radius in meters. Can be `null` (unlimited, default) or `double >= 0`. + * `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings. + * `options.exclude` **[Array][5]?** List of classes to avoid, order does not matter. + * `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) + * `options.alternatives` **[Boolean][4]** Search for alternative routes. (optional, default `false`) + * `options.alternatives` **[Number][6]** Search for up to this many alternative routes. + *Please note that even if alternative routes are requested, a result cannot be guaranteed.* (optional, default `0`) + * `options.steps` **[Boolean][4]** Return route steps for each route leg. (optional, default `false`) + * `options.annotations` **([Array][5] | [Boolean][4])** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`) + * `options.geometries` **[String][3]** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`) + * `options.overview` **[String][3]** Add overview geometry either `full`, `simplified` according to highest zoom level it could be display on, or not at all (`false`). (optional, default `simplified`) + * `options.continue_straight` **[Boolean][4]?** Forces the route to keep going straight at waypoints and don't do a uturn even if it would be faster. Default value depends on the profile. + * `options.approaches` **[Array][5]?** Restrict the direction on the road network at a waypoint, relative to the input coordinate. Can be `null` (unrestricted, default), `curb` or `opposite`. + `null`/`true`/`false` + * `options.waypoints` **[Array][5]?** Indices to coordinates to treat as waypoints. If not supplied, all coordinates are waypoints. Must include first and last coordinate index. + * `options.format` **[String][3]?** Which output format to use, either `json`, or [`flatbuffers`][7]. + * `options.snapping` **[String][3]?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. + * `options.skip_waypoints` **[Boolean][4]** Removes waypoints from the response. Waypoints are still calculated, but not serialized. Could be useful in case you are interested in some other part of response and do not want to transfer waste data. (optional, default `false`) +* `callback` **[Function][8]** + +#### Examples ```javascript var osrm = new OSRM("berlin-latest.osrm"); @@ -82,7 +84,7 @@ osrm.route({coordinates: [[52.519930,13.438640], [52.513191,13.415852]]}, functi }); ``` -Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** An array of [Waypoint](#waypoint) objects representing all waypoints in order AND an array of [`Route`](#route) objects ordered by descending recommendation rank. +Returns **[Object][2]** An array of [Waypoint][9] objects representing all waypoints in order AND an array of [`Route`][10] objects ordered by descending recommendation rank. ### nearest @@ -90,23 +92,24 @@ Snaps a coordinate to the street network and returns the nearest n matches. Note: `coordinates` in the general options only supports a single `{longitude},{latitude}` entry. -**Parameters** +#### Parameters -- `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object literal containing parameters for the nearest query. - - `options.coordinates` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. - - `options.bearings` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. - Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. - - `options.radiuses` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Limits the coordinate snapping to streets in the given radius in meters. Can be `null` (unlimited, default) or `double >= 0`. - - `options.hints` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Hints for the coordinate snapping. Array of base64 encoded strings. - - `options.generate_hints` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) - - `options.number` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Number of nearest segments that should be returned. +* `options` **[Object][2]** Object literal containing parameters for the nearest query. + + * `options.coordinates` **[Array][5]?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. + * `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. + Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. + * `options.radiuses` **[Array][5]?** Limits the coordinate snapping to streets in the given radius in meters. Can be `null` (unlimited, default) or `double >= 0`. + * `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings. + * `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) + * `options.number` **[Number][6]** Number of nearest segments that should be returned. Must be an integer greater than or equal to `1`. (optional, default `1`) - - `options.approaches` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Restrict the direction on the road network at a waypoint, relative to the input coordinate. Can be `null` (unrestricted, default), `curb` or `opposite`. - - `options.format` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Which output format to use, either `json`, or [`flatbuffers`](https://github.com/Project-OSRM/osrm-backend/tree/master/include/engine/api/flatbuffers). - - `options.snapping` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. -- `callback` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** + * `options.approaches` **[Array][5]?** Restrict the direction on the road network at a waypoint, relative to the input coordinate. Can be `null` (unrestricted, default), `curb` or `opposite`. + * `options.format` **[String][3]?** Which output format to use, either `json`, or [`flatbuffers`][7]. + * `options.snapping` **[String][3]?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. +* `callback` **[Function][8]** -**Examples** +#### Examples ```javascript var osrm = new OSRM('network.osrm'); @@ -120,36 +123,37 @@ osrm.nearest(options, function(err, response) { }); ``` -Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** containing `waypoints`. -**`waypoints`**: array of [`Waypoint`](#waypoint) objects sorted by distance to the input coordinate. - Each object has an additional `distance` property, which is the distance in meters to the supplied input coordinate. +Returns **[Object][2]** containing `waypoints`. +**`waypoints`**: array of [`Ẁaypoint`][9] objects sorted by distance to the input coordinate. +Each object has an additional `distance` property, which is the distance in meters to the supplied input coordinate. ### table Computes duration table for the given locations. Allows for both symmetric and asymmetric tables. Optionally returns distance table. -**Parameters** - -- `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object literal containing parameters for the table query. - - `options.coordinates` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. - - `options.bearings` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. - Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. - - `options.radiuses` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Limits the coordinate snapping to streets in the given radius in meters. Can be `null` (unlimited, default) or `double >= 0`. - - `options.hints` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Hints for the coordinate snapping. Array of base64 encoded strings. - - `options.generate_hints` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) - - `options.sources` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** An array of `index` elements (`0 <= integer < #coordinates`) to use - location with given index as source. Default is to use all. - - `options.destinations` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** An array of `index` elements (`0 <= integer < #coordinates`) to use location with given index as destination. Default is to use all. - - `options.approaches` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Restrict the direction on the road network at a waypoint, relative to the input coordinate.. Can be `null` (unrestricted, default), `curb` or `opposite`. - - `options.fallback_speed` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Replace `null` responses in result with as-the-crow-flies estimates based on `fallback_speed`. Value is in metres/second. - - `options.fallback_coordinate` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Either `input` (default) or `snapped`. If using a `fallback_speed`, use either the user-supplied coordinate (`input`), or the snapped coordinate (`snapped`) for calculating the as-the-crow-flies distance between two points. - - `options.scale_factor` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Multiply the table duration values in the table by this number for more controlled input into a route optimization solver. - - `options.snapping` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. - - `options.annotations` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Return the requested table or tables in response. Can be `['duration']` (return the duration matrix, default), `[distance']` (return the distance matrix), or `['duration', distance']` (return both the duration matrix and the distance matrix). -- `callback` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** - -**Examples** +#### Parameters + +* `options` **[Object][2]** Object literal containing parameters for the table query. + + * `options.coordinates` **[Array][5]?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. + * `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. + Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. + * `options.radiuses` **[Array][5]?** Limits the coordinate snapping to streets in the given radius in meters. Can be `null` (unlimited, default) or `double >= 0`. + * `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings. + * `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) + * `options.sources` **[Array][5]?** An array of `index` elements (`0 <= integer < #coordinates`) to use + location with given index as source. Default is to use all. + * `options.destinations` **[Array][5]?** An array of `index` elements (`0 <= integer < #coordinates`) to use location with given index as destination. Default is to use all. + * `options.approaches` **[Array][5]?** Restrict the direction on the road network at a waypoint, relative to the input coordinate.. Can be `null` (unrestricted, default), `curb` or `opposite`. + * `options.fallback_speed` **[Number][6]?** Replace `null` responses in result with as-the-crow-flies estimates based on `fallback_speed`. Value is in metres/second. + * `options.fallback_coordinate` **[String][3]?** Either `input` (default) or `snapped`. If using a `fallback_speed`, use either the user-supplied coordinate (`input`), or the snapped coordinate (`snapped`) for calculating the as-the-crow-flies distance between two points. + * `options.scale_factor` **[Number][6]?** Multiply the table duration values in the table by this number for more controlled input into a route optimization solver. + * `options.snapping` **[String][3]?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. + * `options.annotations` **[Array][5]?** Return the requested table or tables in response. Can be `['duration']` (return the duration matrix, default), `[distance']` (return the distance matrix), or `['duration', distance']` (return both the duration matrix and the distance matrix). +* `callback` **[Function][8]** + +#### Examples ```javascript var osrm = new OSRM('network.osrm'); @@ -168,32 +172,32 @@ osrm.table(options, function(err, response) { }); ``` -Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** containing `durations`, `distances`, `sources`, and `destinations`. +Returns **[Object][2]** containing `durations`, `distances`, `sources`, and `destinations`. **`durations`**: array of arrays that stores the matrix in row-major order. `durations[i][j]` gives the travel time from the i-th waypoint to the j-th waypoint. - Values are given in seconds. +Values are given in seconds. **`distances`**: array of arrays that stores the matrix in row-major order. `distances[i][j]` gives the travel time from the i-th waypoint to the j-th waypoint. - Values are given in meters. -**`sources`**: array of [`Waypoint`](#waypoint) objects describing all sources in order. -**`destinations`**: array of [`Waypoint`](#waypoint) objects describing all destinations in order. +Values are given in meters. +**`sources`**: array of [`Ẁaypoint`][9] objects describing all sources in order. +**`destinations`**: array of [`Ẁaypoint`][9] objects describing all destinations in order. **`fallback_speed_cells`**: (optional) if `fallback_speed` is used, will be an array of arrays of `row,column` values, indicating which cells contain estimated values. ### tile -This generates [Mapbox Vector Tiles](https://mapbox.com/vector-tiles) that can be viewed with a +This generates [Mapbox Vector Tiles][11] that can be viewed with a vector-tile capable slippy-map viewer. The tiles contain road geometries and metadata that can be used to examine the routing graph. The tiles are generated directly from the data in-memory, so are in sync with actual routing results, and let you examine which roads are actually routable, and what weights they have applied. -**Parameters** +#### Parameters -- `ZXY` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array consisting of `x`, `y`, and `z` values representing tile coordinates like - [wiki.openstreetmap.org/wiki/Slippy_map_tilenames](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) - and are supported by vector tile viewers like [Mapbox GL JS](https://www.mapbox.com/mapbox-gl-js/api/). -- `callback` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** +* `ZXY` **[Array][5]** an array consisting of `x`, `y`, and `z` values representing tile coordinates like + [wiki.openstreetmap.org/wiki/Slippy\_map\_tilenames][12] + and are supported by vector tile viewers like [Mapbox GL JS][13]. +* `callback` **[Function][8]** -**Examples** +#### Examples ```javascript var osrm = new OSRM('network.osrm'); @@ -203,37 +207,38 @@ osrm.tile([0, 0, 0], function(err, response) { }); ``` -Returns **[Buffer](https://nodejs.org/api/buffer.html)** contains a Protocol Buffer encoded vector tile. +Returns **[Buffer][14]** contains a Protocol Buffer encoded vector tile. ### match Map matching matches given GPS points to the road network in the most plausible way. -Please note the request might result in multiple sub-traces. Large jumps in the timestamps +Please note the request might result multiple sub-traces. Large jumps in the timestamps (>60s) or improbable transitions lead to trace splits if a complete matching could not be found. The algorithm might not be able to match all points. Outliers are removed -if they cannot be matched successfully. - -**Parameters** - -- `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object literal containing parameters for the match query. - - `options.coordinates` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. - - `options.bearings` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. - Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. - - `options.hints` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Hints for the coordinate snapping. Array of base64 encoded strings. - - `options.generate_hints` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) - - `options.steps` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Return route steps for each route. (optional, default `false`) - - `options.annotations` **([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`) - - `options.geometries` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`) - - `options.overview` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Add overview geometry either `full`, `simplified` according to highest zoom level it could be displayed on, or not at all (`false`). (optional, default `simplified`) - - `options.timestamps` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)>?** Timestamp of the input location (integers, UNIX-like timestamp). - - `options.radiuses` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Standard deviation of GPS precision used for map matching. If applicable use GPS accuracy. Can be `null` for default value `5` meters or `double >= 0`. - - `options.gaps` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Allows the input track splitting based on huge timestamp gaps between points. Either `split` or `ignore`. (optional, default `split`) - - `options.tidy` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Allows the input track modification to obtain better matching quality for noisy tracks. (optional, default `false`) - - `options.waypoints` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Indices to coordinates to treat as waypoints. If not supplied, all coordinates are waypoints. Must include first and last coordinate index. - - `options.snapping` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. -- `callback` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** - -**Examples** +if they can not be matched successfully. + +#### Parameters + +* `options` **[Object][2]** Object literal containing parameters for the match query. + + * `options.coordinates` **[Array][5]?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. + * `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. + Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. + * `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings. + * `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) + * `options.steps` **[Boolean][4]** Return route steps for each route. (optional, default `false`) + * `options.annotations` **([Array][5] | [Boolean][4])** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`) + * `options.geometries` **[String][3]** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`) + * `options.overview` **[String][3]** Add overview geometry either `full`, `simplified` according to highest zoom level it could be display on, or not at all (`false`). (optional, default `simplified`) + * `options.timestamps` **[Array][5]<[Number][6]>?** Timestamp of the input location (integers, UNIX-like timestamp). + * `options.radiuses` **[Array][5]?** Standard deviation of GPS precision used for map matching. If applicable use GPS accuracy. Can be `null` for default value `5` meters or `double >= 0`. + * `options.gaps` **[String][3]** Allows the input track splitting based on huge timestamp gaps between points. Either `split` or `ignore`. (optional, default `split`) + * `options.tidy` **[Boolean][4]** Allows the input track modification to obtain better matching quality for noisy tracks. (optional, default `false`) + * `options.waypoints` **[Array][5]?** Indices to coordinates to treat as waypoints. If not supplied, all coordinates are waypoints. Must include first and last coordinate index. + * `options.snapping` **[String][3]?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. +* `callback` **[Function][8]** + +#### Examples ```javascript var osrm = new OSRM('network.osrm'); @@ -248,23 +253,23 @@ osrm.match(options, function(err, response) { }); ``` -Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** containing `tracepoints` and `matchings`. -**`tracepoints`** Array of [`Waypoint`](#waypoint) objects representing all points of the trace in order. - If the trace point was omitted by map matching because it is an outlier, the entry will be null. - Each `Waypoint` object has the following additional properties, - 1) `matchings_index`: Index to the - [`Route`](#route) object in matchings the sub-trace was matched to, - 2) `waypoint_index`: Index of - the waypoint inside the matched route. - 3) `alternatives_count`: Number of probable alternative matchings for this trace point. A value of zero indicate that this point was matched unambiguously. Split the trace at these points for incremental map matching. -**`matchings`** is an array of [`Route`](#route) objects that assemble the trace. Each `Route` object has an additional `confidence` property, - which is the confidence of the matching. float value between `0` and `1`. `1` is very confident that the matching is correct. +Returns **[Object][2]** containing `tracepoints` and `matchings`. +**`tracepoints`** Array of [`Ẁaypoint`][9] objects representing all points of the trace in order. +If the trace point was omitted by map matching because it is an outlier, the entry will be null. +Each `Waypoint` object has the following additional properties, +1\) `matchings_index`: Index to the +[`Route`][10] object in matchings the sub-trace was matched to, +2\) `waypoint_index`: Index of +the waypoint inside the matched route. +3\) `alternatives_count`: Number of probable alternative matchings for this trace point. A value of zero indicate that this point was matched unambiguously. Split the trace at these points for incremental map matching. +**`matchings`** is an array of [`Route`][10] objects that assemble the trace. Each `Route` object has an additional `confidence` property, +which is the confidence of the matching. float value between `0` and `1`. `1` is very confident that the matching is correct. ### trip The trip plugin solves the Traveling Salesman Problem using a greedy heuristic -(farthest-insertion algorithm) for 10 or more waypoints and uses brute force for less than 10 -waypoints. The returned path does not have to be the shortest path, as TSP is NP-hard it is +(farthest-insertion algorithm) for 10 or \* more waypoints and uses brute force for less than 10 +waypoints. The returned path does not have to be the shortest path, \* as TSP is NP-hard it is only an approximation. Note that all input coordinates have to be connected for the trip service to work. @@ -282,27 +287,28 @@ Right now, the following combinations are possible: | false | any | last | no | | false | any | any | no | -**Parameters** - -- `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object literal containing parameters for the trip query. - - `options.coordinates` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. - - `options.bearings` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. - Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. - - `options.radiuses` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Limits the coordinate snapping to streets in the given radius in meters. Can be `double >= 0` or `null` (unlimited, default). - - `options.hints` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Hints for the coordinate snapping. Array of base64 encoded strings. - - `options.generate_hints` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) - - `options.steps` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Return route steps for each route. (optional, default `false`) - - `options.annotations` **([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`) - - `options.geometries` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`) - - `options.overview` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Add overview geometry either `full`, `simplified` (optional, default `simplified`) - - `options.roundtrip` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Return route is a roundtrip. (optional, default `true`) - - `options.source` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Return route starts at `any` or `first` coordinate. (optional, default `any`) - - `options.destination` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Return route ends at `any` or `last` coordinate. (optional, default `any`) - - `options.approaches` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Restrict the direction on the road network at a waypoint, relative to the input coordinate. Can be `null` (unrestricted, default), `curb` or `opposite`. - - `options.snapping` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. -- `callback` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** - -**Examples** +#### Parameters + +* `options` **[Object][2]** Object literal containing parameters for the trip query. + + * `options.coordinates` **[Array][5]?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees. + * `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction. + Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`. + * `options.radiuses` **[Array][5]?** Limits the coordinate snapping to streets in the given radius in meters. Can be `double >= 0` or `null` (unlimited, default). + * `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings. + * `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`) + * `options.steps` **[Boolean][4]** Return route steps for each route. (optional, default `false`) + * `options.annotations` **([Array][5] | [Boolean][4])** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`) + * `options.geometries` **[String][3]** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`) + * `options.overview` **[String][3]** Add overview geometry either `full`, `simplified` (optional, default `simplified`) + * `options.roundtrip` **[Boolean][4]** Return route is a roundtrip. (optional, default `true`) + * `options.source` **[String][3]** Return route starts at `any` or `first` coordinate. (optional, default `any`) + * `options.destination` **[String][3]** Return route ends at `any` or `last` coordinate. (optional, default `any`) + * `options.approaches` **[Array][5]?** Restrict the direction on the road network at a waypoint, relative to the input coordinate. Can be `null` (unrestricted, default), `curb` or `opposite`. + * `options.snapping` **[String][3]?** Which edges can be snapped to, either `default`, or `any`. `default` only snaps to edges marked by the profile as `is_startpoint`, `any` will allow snapping to any edge in the routing graph. +* `callback` **[Function][8]** + +#### Examples ```javascript var osrm = new OSRM('network.osrm'); @@ -322,33 +328,34 @@ osrm.trip(options, function(err, response) { }); ``` -Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** containing `waypoints` and `trips`. -**`waypoints`**: an array of [`Waypoint`](#waypoint) objects representing all waypoints in input order. - Each Waypoint object has the following additional properties, - 1) `trips_index`: index to trips of the sub-trip the point was matched to, and - 2) `waypoint_index`: index of the point in the trip. -**`trips`**: an array of [`Route`](#route) objects that assemble the trace. +Returns **[Object][2]** containing `waypoints` and `trips`. +**`waypoints`**: an array of [`Waypoint`][9] objects representing all waypoints in input order. +Each Waypoint object has the following additional properties, +1\) `trips_index`: index to trips of the sub-trip the point was matched to, and +2\) `waypoint_index`: index of the point in the trip. +**`trips`**: an array of [`Route`][10] objects that assemble the trace. ## Configuration All plugins support a second additional object that is available to configure some NodeJS specific behaviours. -**Parameters** +### Parameters + +* `plugin_config` **[Object][2]?** Object literal containing parameters for the trip query. -- `plugin_config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Object literal containing parameters for the trip query. - - `plugin_config.format` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** The format of the result object to various API calls. - Valid options are `object` (default if `options.format` is + * `plugin_config.format` **[String][3]?** The format of the result object to various API calls. + Valid options are `object` (default if `options.format` is `json`), which returns a standard Javascript object, as described above, and `buffer`(default if `options.format` is `flatbuffers`), which will return a NodeJS - **[Buffer](https://nodejs.org/api/buffer.html)** object, containing a JSON string or Flatbuffers + **[Buffer][14]** object, containing a JSON string or Flatbuffers object. The latter has the advantage that it can be immediately serialized to disk/sent over the network, and the generation of the string is performed outside the main NodeJS event loop. This option is ignored by the `tile` plugin. Also note that `options.format` set to `flatbuffers` cannot be used with `plugin_config.format` set to `object`. `json_buffer` is deprecated alias for `buffer`. -**Examples** +### Examples ```javascript var osrm = new OSRM('network.osrm'); @@ -370,42 +377,80 @@ osrm.route(options, { format: "buffer" }, function(err, response) { Represents a route through (potentially multiple) waypoints. -**Parameters** +#### Parameters -- `external` **documentation** in - [`osrm-backend`](../http.md#route-object) +* `external` **documentation** in + [`osrm-backend`][15] ### RouteLeg Represents a route between two waypoints. -**Parameters** +#### Parameters -- `external` **documentation** in - [`osrm-backend`](../http.md#routeleg-object) +* `external` **documentation** in + [`osrm-backend`][16] ### RouteStep A step consists of a maneuver such as a turn or merge, followed by a distance of travel along a single way to the subsequent step. -**Parameters** +#### Parameters -- `external` **documentation** in - [`osrm-backend`](../http.md#routestep-object) +* `external` **documentation** in + [`osrm-backend`][17] ### StepManeuver -**Parameters** +#### Parameters -- `external` **documentation** in - [`osrm-backend`](../http.md#stepmaneuver-object) +* `external` **documentation** in + [`osrm-backend`][18] ### Waypoint Object used to describe waypoint on a route. -**Parameters** +#### Parameters + +* `external` **documentation** in + [`osrm-backend`][19] + +[1]: https://github.com/Project-OSRM/osrm-backend + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number + +[7]: https://github.com/Project-OSRM/osrm-backend/tree/master/include/engine/api/flatbuffers + +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function + +[9]: #waypoint + +[10]: #route + +[11]: https://mapbox.com/vector-tiles + +[12]: https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames + +[13]: https://www.mapbox.com/mapbox-gl-js/api/ + +[14]: https://nodejs.org/api/buffer.html + +[15]: ../http.md#route-object + +[16]: ../http.md#routeleg-object + +[17]: ../http.md#routestep-object + +[18]: ../http.md#stepmaneuver-object -- `external` **documentation** in - [`osrm-backend`](../http.md#waypoint-object) +[19]: ../http.md#waypoint-object diff --git a/scripts/build_api_docs.sh b/scripts/build_api_docs.sh index 0ac390bc02..5d0c03f889 100755 --- a/scripts/build_api_docs.sh +++ b/scripts/build_api_docs.sh @@ -14,11 +14,15 @@ babel -V >/dev/null 2>&1 || { echo >&2 "Can't find babel. Add node_modules/.bin browserify --help >/dev/null 2>&1 || { echo >&2 "Can't find browserify. Add node_modules/.bin to your path, or run via \"npm run\""; exit 1; } uglifyjs -V >/dev/null 2>&1 || { echo >&2 "Can't find uglifyjs. Add node_modules/.bin to your path, or run via \"npm run\""; exit 1; } -documentation build src/nodejs/node_osrm.cpp --polyglot --markdown-toc=false -f md -o docs/nodejs/api.md - # Clean up previous version rm -rf build/docs +# Extract JSDoc comments from C++ and generate API docs +# (replaces --polyglot flag removed in documentation.js v14) +mkdir -p build/docs +node scripts/extract_cpp_jsdoc.js src/nodejs/node_osrm.cpp > build/docs/jsdoc-extract.js +documentation build build/docs/jsdoc-extract.js --markdown-toc=false -f md -o docs/nodejs/api.md + # Make temp dir to hold docbox template mkdir -p build/docs/tmp/src diff --git a/scripts/error_on_dirty.sh b/scripts/error_on_dirty.sh index 84e4eadf60..58e11ee02d 100755 --- a/scripts/error_on_dirty.sh +++ b/scripts/error_on_dirty.sh @@ -1,16 +1,38 @@ #!/usr/bin/env bash +# This script checks if any tracked files have been modified. +# It is used in CI to verify that generated files (formatting, documentation, etc.) +# are up to date with their sources. +# +# Usage: ./scripts/error_on_dirty.sh [hint_message] +# +# If files have been modified, the script prints: +# - The list of modified files +# - The diff showing what changed +# - An optional hint message explaining how to fix the issue +# +# Exit codes: +# 0 - No modified files (success) +# 1 - Modified files detected (failure) + set -o errexit set -o pipefail set -o nounset -MSG="The following files have been modified:" +# Optional hint message passed as first argument +HINT_MSG="${1:-}" + dirty=$(git ls-files --modified) if [[ $dirty ]]; then - echo $MSG - echo $dirty + echo "Error: The following files have been modified:" + echo "$dirty" + echo "" git diff + echo "" + if [[ -n "$HINT_MSG" ]]; then + echo "Hint: $HINT_MSG" + fi exit 1 else exit 0 diff --git a/scripts/extract_cpp_jsdoc.js b/scripts/extract_cpp_jsdoc.js new file mode 100644 index 0000000000..b536fd563e --- /dev/null +++ b/scripts/extract_cpp_jsdoc.js @@ -0,0 +1,18 @@ +#!/usr/bin/env node +// Extract JSDoc comments from C++ files for documentation.js +// This replaces the removed --polyglot flag in documentation.js v14+ + +import { readFileSync } from 'fs'; + +if (process.argv.length < 3) { + console.error('Usage: extract_cpp_jsdoc.js '); + process.exit(1); +} + +const input = readFileSync(process.argv[2], 'utf8'); + +// Extract /** ... */ comment blocks (non-greedy match) +const jsdocRegex = /\/\*\*[\s\S]*?\*\//g; +const blocks = input.match(jsdocRegex) || []; + +console.log(blocks.join('\n\n'));