Catch up on docs (#341)

* Catch up on docs

* Fix typo

* Remove unnecessary default arg

apple/DemoApp/Demo/DemoNavigationView.swift

@@ -16,7 +16,7 @@ struct DemoNavigationView: View {
     private let navigationDelegate = NavigationDelegate()
     // NOTE: This is probably not ideal but works for demo purposes.
     // This causes a thread performance checker warning log.
-    private let spokenInstructionObserver = SpokenInstructionObserver.initAVSpeechSynthesizer(isMuted: false)
+    @State private var spokenInstructionObserver = SpokenInstructionObserver.initAVSpeechSynthesizer()
 
     private var locationProvider: LocationProviding
     @ObservedObject private var ferrostarCore: FerrostarCore

guide/src/android-getting-started.md

@@ -226,13 +226,16 @@ such as using a Valhalla [Route Provider](./route-providers.md#bundled-support).
 
 ## Set up voice guidance
 
-Ferrostar is able to process spoken instructions generated from some routing engines.
-The `com.stadiamaps.ferrostar.core.SpokenInstructionObserver` interface
-specifies how to create your own observer.
-A reference implementation is provided in the `AndroidTtsObserver` class,
+If your routes include spoken instructions,
+Ferrostar can trigger the speech synthesis at the right time.
+Ferrostar includes the `AndroidTtsObserver` class,
 which uses the text-to-speech engine built into Android.
-PRs welcome for other popular services (ex: Amazon Polly;
-note that some APIs also provide SSML instructions which work great with this!).
+
+You can also use your own implementation,
+such as a local AI model or cloud service like Amazon Polly.
+The `com.stadiamaps.ferrostar.core.SpokenInstructionObserver` interface
+specifies the required API.
+PRs welcome to add other publicly accessible speech API implementations.
 
 **TODO documentation:**
 
@@ -340,4 +343,4 @@ We've put together a minimal [demo app](https://github.com/stadiamaps/ferrostar/
 
 This covers the basic “batteries included” configuration and pre-built UI.
 But there’s a lot of room for customization!
-Skip on over to the customization chapters that interest you.
+Skip on over to the customization chapters that interest you.

guide/src/ios-getting-started.md

@@ -99,6 +99,60 @@ For limited testing, FOSSGIS maintains a public server with the URL `https://val
 For production use, you’ll need another solution like a [commercial vendor](./vendors.md)
 or self-hosting.
 
+### Set up Voice Guidance
+
+If your routes include spoken instructions,
+Ferrostar can trigger the speech synthesis at the right time.
+Ferrostar includes the `SpokenInstructionObserver` class, 
+which can use `AVSpeechSynthesizer` or your own speech synthesis.
+
+The `SpeechSynthesizer` protocol
+specifies the required interface,
+and you can build your own implementation on this,
+such as a local AI model or cloud service like Amazon Polly.
+PRs welcome to add other publicly accessible speech API implementations.
+
+Your navigation view can store the spoken instruction observer as an instance variable:
+
+```swift
+@State private var spokenInstructionObserver = SpokenInstructionObserver.initAVSpeechSynthesizer()
+```
+
+Then, you'll need to configure `FerrostarCore` to use it.
+
+```swift
+ferrostarCore.spokenInstructionObserver = spokenInstructionObserver
+```
+
+Finally, you can use this to drive state on navigation view.
+`DynamicallyOrientingNavigationView` has constructor arguments to configure the mute button UI.
+See the demo app for an example.
+
+### Configure annotation parsing
+
+`FerrostarCore` includes support for parsing arbitrary annotations
+from the route.
+This technique is a de facto standard from OSRM,
+and has been adopted by a wide range of open-source and proprietary solutions.
+The routing APIs from Stadia Maps, Mapbox, and others
+use this to include detailed information like speed limits,
+expected travel speed, and more.
+
+Ferrostar includes a Valhalla extended OSRM annotation parser,
+which works with Valhalla-powered APIs including Stadia Maps.
+The implementation is completely generic,
+so you can define your own model to include custom parameters.
+PRs welcome for other public API annotation models.
+
+To set up annotation parsing,
+simply pass the optional `annotation:` parameter
+to the `FerrostarCore` constructor.
+You can create a Valhalla extended OSRM annotation publisher like so:
+
+```swift
+AnnotationPublisher<ValhallaExtendedOSRMAnnotation>.valhallaExtendedOSRM()
+```
+
 ## Getting a route
 
 Before getting routes, you’ll need the user’s current location.
@@ -178,4 +232,4 @@ We've put together a minimal [demo app](https://github.com/stadiamaps/ferrostar/
 
 This covers the basic “batteries included” configuration and pre-built UI.
 But there’s a lot of room for customization!
-Skip on over to the customization chapters that interest you.
+Skip on over to the customization chapters that interest you.