Enhance README and documentation with compatibility details, usage ex…

README.md

@@ -21,21 +21,15 @@ The rest of the functionality is organized in submodules with the following feat
 
 All modules expose the full configuration and parameter handling API of OSRM through setter and getter functions, providing fine-grained control over query behavior.
 
-### Output format — why FlatBuffers?
+All query modules (Nearest, Route, Table, Match, Trip) return by default an object whose types are auto-generated (see `gen/generate.jl`) from OSRM's FlatBuffers schema files. Alternatively, one can receive the binary FlatBuffers response directly.
 
-All query modules (Nearest, Route, Table, Match, Trip) return responses as FlatBuffers binary data rather than JSON. This is by design:
-
-- **Auto-generated types** — The Julia response types (`FBResult`, `RouteObject`, `Waypoint`, `TableResult`, etc.) are auto-generated directly from OSRM's official `.fbs` schema files (see `gen/generate.jl`). This guarantees they always match the upstream OSRM data model exactly, with no manual translation layer.
-- **Zero-copy deserialization** — The binary response is wrapped in an `IOBuffer` and read directly into native Julia structs, with no parsing overhead.
-- **Pipeline integration** — The resulting typed Julia structs plug directly into downstream data pipelines without conversion steps.
-
-The **Tile** module is the exception — it returns road network geometry in MVT format (Mapbox Vector Tiles).
+The Tile module is the exception — it returns road network geometry in MVT format (Mapbox Vector Tiles).
 
 ## Installation
 
 ```julia
 using Pkg
-Pkg.add(url="https://github.com/moviro-hub/OpenSourceRoutingMachine.jl")
+Pkg.add("OpenSourceRoutingMachine")
 ```
 
 ## Workflow
@@ -168,15 +162,15 @@ using OpenSourceRoutingMachine.Table
 
 params = TableParams()
 # Add coordinates first
-add_coordinate!(params, Position(9.9937, 53.5511))  # Index 0
-add_coordinate!(params, Position(9.9882, 53.6304))  # Index 1
-add_coordinate!(params, Position(9.9667, 53.5417))  # Index 2
-add_coordinate!(params, Position(9.9352, 53.5528))  # Index 3
+add_coordinate!(params, Position(9.9937, 53.5511))
+add_coordinate!(params, Position(9.9882, 53.6304))
+add_coordinate!(params, Position(9.9667, 53.5417))
+add_coordinate!(params, Position(9.9352, 53.5528))
 # Mark which coordinates are origins and destinations
-add_source!(params, 0)
-add_source!(params, 1)
-add_destination!(params, 2)
-add_destination!(params, 3)
+add_source!(params, 1)       # first coordinate
+add_source!(params, 2)       # second coordinate
+add_destination!(params, 3)  # third coordinate
+add_destination!(params, 4)  # fourth coordinate
 # see the documentation for more parameters
 
 response = table(osrm, params)
@@ -246,6 +240,6 @@ set_z!(params, 13)    # Zoom level
 response = tile(osrm, params)
 ```
 
-Copyright (c) 2025 MOVIRO GmbH
+Copyright (c) 2025–2026 MOVIRO GmbH
 
 Licensed under the MIT License.

docs/src/examples.md

@@ -118,15 +118,15 @@ using OpenSourceRoutingMachine.Table
 
 params = TableParams()
 # Add coordinates first
-add_coordinate!(params, Position(9.9937, 53.5511))  # Index 0
-add_coordinate!(params, Position(9.9882, 53.6304))  # Index 1
-add_coordinate!(params, Position(9.9667, 53.5417))  # Index 2
-add_coordinate!(params, Position(9.9352, 53.5528))  # Index 3
+add_coordinate!(params, Position(9.9937, 53.5511))
+add_coordinate!(params, Position(9.9882, 53.6304))
+add_coordinate!(params, Position(9.9667, 53.5417))
+add_coordinate!(params, Position(9.9352, 53.5528))
 # Mark which coordinates are origins and destinations
-add_source!(params, 0)
 add_source!(params, 1)
-add_destination!(params, 2)
+add_source!(params, 2)
 add_destination!(params, 3)
+add_destination!(params, 4)
 # see the documentation for more parameters
 
 response = table(osrm, params)

docs/src/index.md

@@ -1,14 +1,15 @@
 # OpenSourceRoutingMachine.jl
 
-A thin Julia wrapper for OSRM (Open Source Routing Machine), a high-performance tool for route planning in road networks.
+A thin Julia wrapper for [OSRM](https://project-osrm.org/) (Open Source Routing Machine), a high-performance routing engine for road networks.
+Use it to build routing graphs from OpenStreetMap data and query them for routes, duration/distance matrices, map matching, and more — all from within Julia.
 
 ## Modules
 
-The package structure consists of a core module and service submodules.
+The package structure consists of a core module and several submodules.
 
 The core module `OpenSourceRoutingMachine` provides the constructor `OSRM` for creating an OSRM instance and setter and getter functions for basic configuration.
 
-The rest of the functionality is organized in service submodules with the following scope:
+The rest of the functionality is organized in submodules with the following features:
 
 - **Graph**: Builds OSRM graphs from OpenStreetMap data
 - **Nearest**: Find the nearest waypoint in a road network for a given position
@@ -19,17 +20,19 @@ The rest of the functionality is organized in service submodules with the follow
 - **Tile**: Retrieve road network geometry as vector tiles
 
 All modules expose the full configuration and parameter handling API of OSRM through setter and getter functions, providing fine-grained control over query behavior.
-The output format is restricted to FlatBuffers for all modules except the Tile module.
-The Tile module returns road network geometry in MVT format.
+
+All query modules (Nearest, Route, Table, Match, Trip) return by default an object whose types are auto-generated (see `gen/generate.jl`) from OSRM's FlatBuffers schema files. Alternatively, one can receive the binary FlatBuffers response directly.
+
+The Tile module is the exception — it returns road network geometry in MVT format (Mapbox Vector Tiles).
 
 ## Installation
 
 ```julia
 using Pkg
-Pkg.add("OpenSourceRoutingMachine", url="https://github.com/moviro-hub/OpenSourceRoutingMachine.jl")
+Pkg.add("OpenSourceRoutingMachine")
 ```
 
-See the `Examples` section for end-to-end usage patterns.
+See the [Examples](@ref) section for end-to-end usage patterns.
 
 ## API Reference