Clean up the docs

afarber · afarber · commit bc9f80da2b4e · 2025-10-30T17:51:44.000+01:00
diff --git a/README.md b/README.md
@@ -26,8 +26,8 @@ The library is available on [Maven Central](https://central.sonatype.com/artifac
 - Lightweight, pure Kotlin implementation with zero Google dependencies
 - OSM tiles via standard APIs (free, no API keys required)
 - Smooth camera animations with customizable durations and callbacks
-- 7 overlay types: Markers, Polylines, Polygons, Circles, Ground Overlays, Tile Overlays, Info Windows
-- 5 map types: Normal (OSM), Terrain (OpenTopoMap), Humanitarian, Cycle, None
+- Multiple overlay types: Markers, Polylines, Polygons, Circles, Ground Overlays, Tile Overlays, Info Windows
+- Multiple map types (see [Map Types Guide](docs/MAP_TYPES.md))
 - Built-in zoom controls (+/- buttons) via UiSettings
 - External app integration (open in Google Maps, OsmAnd, etc. via geo: URI)
 - GeoJSON import support
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -92,7 +92,7 @@ If issues are found, the commit is blocked and instructions are displayed.
 
 ### Unit Tests
 
-All new features and bug fixes should include unit tests.
+All new features and bug fixes should include unit tests. See [Unit Testing Guide](TESTING_UNIT.md) for detailed information on writing tests with Robolectric.
 
 Run unit tests:
 
@@ -102,7 +102,7 @@ Run unit tests:
 
 ### Test Coverage
 
-The project enforces a minimum test coverage of 20% for all code. Coverage is measured using JaCoCo.
+The project enforces a **minimum test coverage of 20%** for all code. Coverage is measured using JaCoCo.
 
 Generate coverage report:
 
@@ -121,7 +121,7 @@ Check coverage meets minimum threshold:
 ./scripts/check-coverage.sh
 ```
 
-The CI pipeline will fail if coverage drops below 20%. Focus on testing:
+The CI pipeline will fail if coverage drops below the minimum threshold. Focus on testing:
 - Core business logic
 - Public API methods
 - Edge cases and error handling
diff --git a/docs/GITHUB_WORKFLOWS.md b/docs/GITHUB_WORKFLOWS.md
@@ -40,7 +40,7 @@ Located in `.github/workflows/`:
 
 #### `_coverage.yml`
 - **Purpose**: Check test coverage meets minimum threshold
-- **Runs**: `./scripts/check-coverage.sh` (minimum 20% coverage)
+- **Runs**: `./scripts/check-coverage.sh` (minimum threshold defined in [Contributing Guide](CONTRIBUTING.md#test-coverage))
 - **Artifacts**: Uploads coverage reports to Codecov and as artifacts
 - **Usage**: Called by CI workflow
 - **Duration**: ~1-2 minutes
@@ -495,16 +495,6 @@ This single workflow definition powers both daily scheduled tests and PR validat
 - Builds ensure compilation works
 - Publish handles distribution
 
-## Future Enhancements
-
-Possible additions:
-
-- **Instrumentation Tests**: Run UI tests on Android emulator
-- **Code Coverage**: Upload coverage reports to Codecov
-- **Dependency Updates**: Automated PRs for dependency updates (Renovate/Dependabot)
-- **Release Drafter**: Automated changelog generation from PR labels
-- **Benchmark Tracking**: Performance regression detection
-- **Doc Generation**: Auto-generate KDoc documentation
 
 ## Monitoring
 
@@ -541,4 +531,4 @@ The OpenMapView GitHub Actions setup provides:
 - **Easy maintenance** - Change configuration once
 - **Full automation** - From code change to Maven Central
 
-For Maven Central setup details, see [MAVEN_CENTRAL_SETUP.md](MAVEN_CENTRAL_SETUP.md).
+For Maven Central setup details, see [Publishing Guide](PUBLISHING.md).
diff --git a/docs/LIFECYCLE.md b/docs/LIFECYCLE.md
@@ -140,23 +140,19 @@ fun MapViewScreen() {
 ```kotlin
 fun onResume() {
     // Called when app comes to foreground
-    // Could be used to resume tile downloads if paused
 }
 ```
 
-**Current implementation:** Does nothing (tiles continue downloading)
-**Future optimization:** Could resume paused downloads
+**Current implementation:** Performs necessary resume operations.
 
 ### onPause()
 ```kotlin
 fun onPause() {
     // Called when app goes to background
-    // Could be used to pause tile downloads to save battery
 }
 ```
 
-**Current implementation:** Does nothing (tiles continue downloading)
-**Future optimization:** Could pause ongoing downloads to save battery
+**Current implementation:** Performs necessary pause operations.
 
 ### onDestroy()
 ```kotlin
@@ -169,11 +165,7 @@ fun onDestroy() {
 }
 ```
 
-**Current implementation:** Full cleanup!
-- Cancels all running tile downloads
-- Closes Ktor HTTP client
-- Clears bitmap memory cache (LRU cache for tiles)
-- Clears marker icon cache (up to 10 colored marker icons)
+**Current implementation:** Full cleanup - cancels all running operations, closes network clients, and clears caches.
 
 ## Best Practices
 
@@ -250,18 +242,8 @@ If you forget to register the lifecycle observer:
 
 ## Example Apps
 
-All three example apps demonstrate proper lifecycle management:
+Example applications in the `examples/` directory demonstrate proper lifecycle management. Each example shows the same pattern:
 
-### Example01Pan
-Basic panning with lifecycle observer registration.
-
-### Example02Zoom
-Zoom controls (pinch, buttons) with lifecycle observer registration.
-
-### Example03Markers
-Markers with colors and click handling with lifecycle observer registration.
-
-Each example shows the same pattern:
 ```kotlin
 AndroidView(
     factory = { context ->
diff --git a/docs/MAP_TYPES.md b/docs/MAP_TYPES.md
@@ -169,24 +169,22 @@ mapView.setMapType(MapType.TRACESTRACK_TOPO)
 ```
 
 #### 9. MAPTILER_OMT - OpenMapTiles Vector Style
-**`MapType.MAPTILER_OMT`** (constant value: 9) 🔑🚧 **Coming Soon**
+**`MapType.MAPTILER_OMT`** (constant value: 9) 🔑🚧 **Not Yet Supported**
 
 High-quality vector tile map based on OpenMapTiles schema.
 
 - **Status**: Not yet supported - requires MapLibre GL integration
-- **When Available**: Smooth rendering, client-side styling, excellent performance
 - **Get API Key**: https://www.maptiler.com/cloud/plans/
 - **Free Tier**: 100,000 tiles/month
 
-### Vector Tile Support (Coming Soon)
+### Vector Tile Support
 
 #### 10. SHORTBREAD - Modern Vector Style
-**`MapType.SHORTBREAD`** (constant value: 8) 🚧 **Coming Soon**
+**`MapType.SHORTBREAD`** (constant value: 8) 🚧 **Not Yet Supported**
 
 Modern, clean vector-based map style.
 
 - **Status**: Not yet supported - requires MapLibre GL integration
-- **When Available**: Smooth rendering, customizable styling
 - **No API Key Required**
 
 ## API Key Configuration
@@ -341,11 +339,6 @@ mapView.setMapType(MapType.CYCLOSM)  // Switch map types dynamically
 - **Public API**: See `docs/PUBLIC_API.md` for complete API reference
 - **Tile Specifications**: All maps use 256×256 pixel tiles, Web Mercator projection (EPSG:3857)
 
-## Future Enhancements
-
-- **Vector Tile Support**: MapLibre GL integration for SHORTBREAD and MAPTILER_OMT (planned)
-- **Dark Mode Variants**: TransportDarkMap, ShortbreadEclipse (considering for future release)
-- **Additional Free Maps**: Evaluating other public tile sources
 
 ---
 
diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md
@@ -338,17 +338,6 @@ With prefetching enabled:
 - **Pan gesture:** 0-4 tile downloads (~0-150KB) from cache
 - **Zoom change:** 0-20 tile downloads (~0-700KB) depending on zoom delta
 
-## Future Optimizations
-
-Potential areas for further improvement:
-
-1. **Bitmap pooling** - Reuse bitmap objects to reduce allocations
-2. **Tile compression** - Store tiles in WebP format in disk cache
-3. **Vector tiles** - Support vector-based rendering for reduced bandwidth
-4. **Adaptive prefetch** - Adjust buffer size based on panning velocity
-5. **Render throttling** - Limit draw calls during rapid gestures
-6. **Tile source selection** - Support multiple tile providers with fallback
-7. **Offline mode** - Bundle common area tiles in APK
 
 ## Benchmarking
 
@@ -372,9 +361,9 @@ Choreographer.getInstance().postFrameCallback { frameTimeNanos ->
 
 ## Best Practices
 
-For optimal performance in your app:
+For optimal performance:
 
-1. **Lifecycle integration:** Always call lifecycle methods (onResume, onPause, onDestroy)
+1. **Lifecycle integration:** Register OpenMapView with lifecycle observer (see [Lifecycle Management](LIFECYCLE.md))
 2. **Memory limits:** Monitor memory usage if displaying multiple maps simultaneously
 3. **Cache clearing:** Provide UI to clear cache if storage becomes an issue
 4. **Network awareness:** Consider pausing downloads on metered connections
diff --git a/docs/PUBLIC_API.md b/docs/PUBLIC_API.md
@@ -16,11 +16,11 @@ This document lists all public non-deprecated methods from Google's MapView and
 | `onPause()`                       | `void`      |                                                                    |
 | `onStop()`                        | `void`      | Not needed - OpenMapView uses DefaultLifecycleObserver pattern     |
 | `onDestroy()`                     | `void`      |                                                                    |
-| `onSaveInstanceState(Bundle)`     | `void`      | Not yet implemented - state persistence planned for future release |
-| `onLowMemory()`                   | `void`      | Not yet implemented - memory management optimization planned       |
+| `onSaveInstanceState(Bundle)`     | `void`      | Not implemented                                                     |
+| `onLowMemory()`                   | `void`      | Not implemented                                                     |
 | `getMapAsync(OnMapReadyCallback)` | `void`      | Not needed - map is immediately available after view creation      |
-| `onEnterAmbient(Bundle)`          | `void`      | Not planned - wearable-specific feature                            |
-| `onExitAmbient()`                 | `void`      | Not planned - wearable-specific feature                            |
+| `onEnterAmbient(Bundle)`          | `void`      | Not implemented - wearable-specific feature                         |
+| `onExitAmbient()`                 | `void`      | Not implemented - wearable-specific feature                         |
 
 ---
 
@@ -77,7 +77,7 @@ This document lists all public non-deprecated methods from Google's MapView and
 | `getZoom()`                    | `double`    | Direct method on OpenMapView (not via separate GoogleMap object) |
 | `setMapType(int)`              | `void`      | Supports NORMAL, TERRAIN, HUMANITARIAN, CYCLE, NONE              |
 | `getMapType()`                 | `int`       |                                                                  |
-| `setMapStyle(MapStyleOptions)` | `boolean`   | Not planned - custom tile sources could provide this             |
+| `setMapStyle(MapStyleOptions)` | `boolean`   | Not implemented                                                   |
 
 ---
 
@@ -115,15 +115,15 @@ Methods available on the UiSettings object returned by `getUiSettings()`:
 | `isZoomControlsEnabled()`                             | `boolean`   |                                                                                          |
 | `setScrollGesturesEnabledDuringRotateOrZoom(boolean)` | `void`      |                                                                                          |
 | `isScrollGesturesEnabledDuringRotateOrZoom()`         | `boolean`   |                                                                                          |
-| `setRotateGesturesEnabled(boolean)`                   | `void`      | Not planned - OSM tiles don't support rotation                                           |
+| `setRotateGesturesEnabled(boolean)`                   | `void`      | Not implemented                                                                           |
 | `isRotateGesturesEnabled()`                           | `boolean`   | Always returns false                                                                     |
-| `setTiltGesturesEnabled(boolean)`                     | `void`      | Not planned - OSM tiles don't support 3D tilt                                            |
+| `setTiltGesturesEnabled(boolean)`                     | `void`      | Not implemented                                                                           |
 | `isTiltGesturesEnabled()`                             | `boolean`   | Always returns false                                                                     |
-| `setCompassEnabled(boolean)`                          | `void`      | Not planned - requires rotation support                                                  |
+| `setCompassEnabled(boolean)`                          | `void`      | Not implemented                                                                           |
 | `isCompassEnabled()`                                  | `boolean`   | Always returns false                                                                     |
-| `setMyLocationButtonEnabled(boolean)`                 | `void`      | Not planned - requires location services integration                                     |
+| `setMyLocationButtonEnabled(boolean)`                 | `void`      | Not implemented                                                                           |
 | `isMyLocationButtonEnabled()`                         | `boolean`   | Always returns false                                                                     |
-| `setIndoorLevelPickerEnabled(boolean)`                | `void`      | Not planned - no indoor mapping support                                                  |
+| `setIndoorLevelPickerEnabled(boolean)`                | `void`      | Not implemented                                                                           |
 | `isIndoorLevelPickerEnabled()`                        | `boolean`   | Always returns false                                                                     |
 | `setMapToolbarEnabled(boolean)`                       | `void`      | Not implemented - use openInExternalApp() instead (see External Map Integration section) |
 | `isMapToolbarEnabled()`                               | `boolean`   | Always returns false                                                                     |
@@ -135,11 +135,11 @@ Methods available on the UiSettings object returned by `getUiSettings()`:
 
 | Method                         | Return Type | Notes                                                |
 | ------------------------------ | ----------- | ---------------------------------------------------- |
-| `setTrafficEnabled(boolean)`   | `void`      | Not planned - requires traffic data source           |
+| `setTrafficEnabled(boolean)`   | `void`      | Not implemented                                       |
 | `isTrafficEnabled()`           | `boolean`   | Always returns false                                 |
-| `setBuildingsEnabled(boolean)` | `void`      | Not planned - OSM tiles include buildings by default |
+| `setBuildingsEnabled(boolean)` | `void`      | Not implemented - OSM tiles include buildings by default |
 | `isBuildingsEnabled()`         | `boolean`   | Always returns true                                  |
-| `setIndoorEnabled(boolean)`    | `void`      | Not planned - requires indoor mapping data           |
+| `setIndoorEnabled(boolean)`    | `void`      | Not implemented                                       |
 | `isIndoorEnabled()`            | `boolean`   | Always returns false                                 |
 
 ---
@@ -185,7 +185,7 @@ OpenMapView provides comprehensive event listener support using Kotlin `fun inte
 | `setOnPolygonClickListener(OnPolygonClickListener)`                   | `void`           |                                                                      |
 | `setOnCircleClickListener(OnCircleClickListener)`                     | `void`           |                                                                      |
 | `setOnGroundOverlayClickListener(OnGroundOverlayClickListener)`       | `void`           |                                                                      |
-| `setOnPoiClickListener(OnPoiClickListener)`                           | `void`           | Not planned - POI data not available in OSM tiles                    |
+| `setOnPoiClickListener(OnPoiClickListener)`                           | `void`           | Not implemented - POI data not available in OSM tiles                 |
 | `setOnCameraMoveStartedListener(OnCameraMoveStartedListener)`         | `void`           |                                                                      |
 | `setOnCameraMoveListener(OnCameraMoveListener)`                       | `void`           |                                                                      |
 | `setOnCameraIdleListener(OnCameraIdleListener)`                       | `void`           |                                                                      |
@@ -197,8 +197,8 @@ OpenMapView provides comprehensive event listener support using Kotlin `fun inte
 | `setOnInfoWindowLongClickListener(OnInfoWindowLongClickListener)`     | `void`           | Not implemented                                                      |
 | `setOnMyLocationButtonClickListener(OnMyLocationButtonClickListener)` | `void`           | Not implemented                                                      |
 | `setOnMyLocationClickListener(OnMyLocationClickListener)`             | `void`           | Not implemented                                                      |
-| `setOnIndoorStateChangeListener(OnIndoorStateChangeListener)`         | `void`           | Not planned - indoor mapping not supported                           |
-| `getFocusedBuilding()`                                                | `IndoorBuilding` | Not planned - indoor mapping not supported                           |
+| `setOnIndoorStateChangeListener(OnIndoorStateChangeListener)`         | `void`           | Not implemented - indoor mapping not supported                        |
+| `getFocusedBuilding()`                                                | `IndoorBuilding` | Not implemented - indoor mapping not supported                        |
 
 **Event Priority (highest to lowest):**
 
diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md
@@ -307,7 +307,8 @@ The release process is orchestrated by reusable GitHub Actions workflows:
 
 - [GitHub Workflows](GITHUB_WORKFLOWS.md) - CI/CD pipeline details
 - [Contributing Guide](CONTRIBUTING.md) - Contribution guidelines
-- [Testing Guide](TESTING.md) - Testing documentation
+- [Unit Testing Guide](TESTING_UNIT.md) - Unit testing with Robolectric
+- [Instrumented Testing Guide](TESTING_INSTRUMENTED.md) - On-device testing
 
 ## Migration Notes
 
diff --git a/docs/REPLACING_GOOGLE_MAPS.md b/docs/REPLACING_GOOGLE_MAPS.md
@@ -451,19 +451,7 @@ mapView.post {
 
 ## Code Examples
 
-See working example applications in the repository:
-
-- [Example01Pan](../examples/Example01Pan) - Basic map panning
-- [Example02Zoom](../examples/Example02Zoom) - Zoom controls
-- [Example03Markers](../examples/Example03Markers) - Marker overlays
-- [Example04Polylines](../examples/Example04Polylines) - Lines and polygons
-- [Example05Camera](../examples/Example05Camera) - Camera animations
-- [Example06Clicks](../examples/Example06Clicks) - Click listeners
-- [Example07DraggableMarkers](../examples/Example07DraggableMarkers) - Draggable markers
-- [Example08Circles](../examples/Example08Circles) - Circle overlays
-- [Example09Overlays](../examples/Example09Overlays) - Tile overlays
-- [Example10GroundOverlays](../examples/Example10GroundOverlays) - Ground overlays
-- [Example11MapTypes](../examples/Example11MapTypes) - Map type switching
+See working example applications in the `examples/` directory of the repository, covering features like basic panning, zoom controls, markers, polylines, camera animations, click listeners, draggable markers, circles, tile overlays, ground overlays, and map type switching.
 
 ---
 
@@ -472,10 +460,10 @@ See working example applications in the repository:
 1. **Read the API compatibility matrix**: [PUBLIC_API.md](PUBLIC_API.md)
 2. **Understand the architecture**: [ARCHITECTURE.md](ARCHITECTURE.md)
 3. **Learn lifecycle management**: [LIFECYCLE.md](LIFECYCLE.md)
-4. **Explore tile overlays**: [TILE_OVERLAYS.md](TILE_OVERLAYS.md)
+4. **Explore map types**: [MAP_TYPES.md](MAP_TYPES.md)
 5. **Review API documentation**: [https://afarber.github.io/OpenMapView/](https://afarber.github.io/OpenMapView/)
-6. **Try the examples**: Clone the repository and run example apps
-7. **Join the community**: Report issues or contribute on [GitHub](https://github.com/afarber/OpenMapView)
+6. **Try the examples**: Clone the repository and run example apps in `examples/` directory
+7. **Report issues**: [GitHub Issues](https://github.com/afarber/OpenMapView/issues)
 
 ---
 
diff --git a/docs/TESTING_INSTRUMENTED.md b/docs/TESTING_INSTRUMENTED.md
diff --git a/docs/TESTING_UNIT.md b/docs/TESTING_UNIT.md
