chore(directions): README improvements (#404) [skip ci]

Ombuweb · web-flow · commit b88de93c5d83 · 2023-01-17T18:27:48.000-08:00
diff --git a/packages/directions/README.md b/packages/directions/README.md
@@ -1,122 +1,53 @@
 # @nativescript/directions
+<!-- TODO: Add Preview -->
+## Installation
 
 ```cli
 npm install @nativescript/directions
 ```
 
 ## Usage
+### Importing
+Once you have installed the plugin, import and create an instance of the `Directions` class.
+```ts
+import { Directions } from "@nativescript/directions"
 
-### Demo app (XML + TypeScript)
-
-Want to dive in quickly? Check out [the demo app](https://github.com/EddyVerbruggen/nativescript-directions/tree/9a9f1ff0de551c447a87b3513a5453f1b962c33c/demo)! Otherwise, continue reading.
-
-You can run the demo app from the root of the project by typing `npm run demo.ios.device` or `npm run demo.android`.
-
-<img src="https://raw.githubusercontent.com/EddyVerbruggen/nativescript-directions/master/media/directions-animated.gif" width="320px" height="570px"/>
-
-### Demo app (Angular)
-
-This plugin is part of the [plugin showcase app](https://github.com/EddyVerbruggen/nativescript-pluginshowcase/tree/master/app/mapping) I built using Angular.
-
-## API
-
-### `available`
-
-Not all devices have the Google (Android) or Apple (iOS) Maps app installed. Well, most do of course, but on an Android simulator you may be out of luck, so let's check beforehand:
-
-##### JavaScript
-
-```js
-// require the plugin
-var directions = require('@nativescript/directions');
-
-// instantiate the plugin
-var directions = new directions.Directions();
-
-directions.Directions.available().then(function (avail) {
-	console.log(avail ? 'Yes' : 'No');
-});
+const directions = new Directions()
 ```
 
-##### TypeScript
-
-```typescript
-// require the plugin
-import { Directions } from '@nativescript/directions';
+### Checking for support
 
-// instantiate the plugin
-let directions = new Directions();
+To check if the device has a Maps application installed, call the `available` method.
+```ts
+directions.available().then((avail:boolean) => {
 
-directions.available().then((avail) => {
 	console.log(avail ? 'Yes' : 'No');
 });
 ```
-
-### `navigate`
-
-This function opens the native Maps app with a predefined `from` and `to` address.
-
-If you don't pass `from` the current location of the user will be used.
-
-If an `address` is specified then `lat` and `lng` will be ignored.
-
-If you pass in an Array of `to` addresses, then the last item is the destination, the others become 'waypoints'.
-
-Note that if there's an ocean in between `from` and `to` you won't be able to get directions, don't blame this plugin for that 😁
-
-##### JavaScript
-
-```js
-directions
-	.navigate({
-		from: {
-			// optional, default 'current location'
-			lat: 52.215987,
-			lng: 5.282764,
-		},
-		to: {
-			// either pass in a single object or an Array (see the TypeScript example below)
-			address: 'Hof der Kolommen 34, Amersfoort, Netherlands',
-		},
-		// for platform-specific options, see the TypeScript example below.
-	})
-	.then(
-		function () {
-			console.log('Maps app launched.');
-		},
-		function (error) {
-			console.log(error);
-		}
-	);
-```
-
-##### TypeScript
-
+To open the Google (Android) or Apple (iOS) Maps app with the desired directions, call the `navigate` method.
 ```typescript
 directions
 	.navigate({
 		from: {
-			// optional, default 'current location'
 			lat: 52.215987,
 			lng: 5.282764,
 		},
 		to: [
 			{
-				// if an Array is passed (as in this example), the last item is the destination, the addresses in between are 'waypoints'.
 				address: 'Hof der Kolommen 34, Amersfoort, Netherlands',
 			},
 			{
 				address: 'Aak 98, Wieringerwerf, Netherlands',
 			},
 		],
-		type: 'walking', // optional, can be: driving, transit, bicycling or walking
+		type: 'walking', 
 		ios: {
-			preferGoogleMaps: true, // If the Google Maps app is installed, use that one instead of Apple Maps, because it supports waypoints. Default true.
-			allowGoogleMapsWeb: true, // If waypoints are passed in and Google Maps is not installed, you can either open Apple Maps and the first waypoint is used as the to-address (the rest is ignored), or you can open Google Maps on web so all waypoints are shown (set this property to true). Default false.
-			useUniversalSyntax: true, // Prefer the Universal URL Syntax to the comgooglemaps:// url scheme. Useful if Google Maps does not load correctly.
+			preferGoogleMaps: true, 
+			allowGoogleMapsWeb: true, 
+			useUniversalSyntax: true, 
 		},
 		android: {
-			newTask: true, // Start as new task. This means it will start a new history stack instead of using the current app. Default true.
+			newTask: true, 
 		},
 	})
 	.then(
@@ -129,9 +60,47 @@ directions
 	);
 ```
 
-## Future work
+## API
+### Method(s)
+
+| Name | Return Type | Description |
+|------|-------------|-------------|
+| `available()` | `Promise<boolean>` | Checks if the device has the Maps application installed. |
+| `navigate(options: NavigateToOptions)`| `Promise<void>` | Opens the native Maps app with a predefined `from` and `to` address and [other](#navigatetooptions) optional settings.|
+
+### AddressOptions
+| Name| Type | Description|
+|-----|------|------------|
+| `lat` | `number` | _Optional_: The latitude. Ignored if `address`' is set.|
+| `lng` | `number` | _Optional_: The longitude. Ignored if `address`' is set. |
+| `address` | `string` | _Optional_: The address of the direction. For multiple addresses, add them to the string separating them with a comma.|
+
+### NavigateToOptionsType
+```ts
+'driving' | 'transit' | 'bicycling' | 'walking'
+```
 
-- Perhaps add Android-specific options like opening the map in StreetView mode, or pre-defining the transportation type (walk/bike/car).
+### NavigateToOptions
+| Name| Type | Description|
+|-----|------|------------|
+| `from`| [AddressOptions](#addressoptions)| _Optional_: The starting point for the navigation. <br><br>If this option is not passed, the current location of the user will be used.|
+| `to` | [AddressOptions](#addressoptions) \| Array<[AddressOptions](#addressoptions)>| The destination of the navigation. If it's an array of addresses, then the last item is the destination, the others become 'waypoints'.|
+| `ios` | [iOSOptions](#iosoptions) | _Optional_: iOS-specific settings. |
+| `android` | [AndroidOptions](#androidoptions) | _Optional_:  Android-specific settings. |
+| `useUniversalSyntax` | `boolean` | _Optional_: If `true`, this opens Google Maps using the universal syntax rather than the comgooglemaps:// url scheme. Use this if Google Maps does not load correctly on iOS, the Universal Syntax is now preferred.|
+| `type` | [NavigateToOptionsType](#navigatetooptionstype) | _Optional_: The mode of reaching to the destionation. |
+
+>**Note** that if there's an ocean in between `from` and `to` you won't be able to get directions, don't blame this plugin for that 😁.
+### iOSOptions
+| Name| Type | Description|
+|-----|------|------------|
+| `preferGoogleMaps`| `boolean`| _Optional_: Indicates whether to use Google Maps(if installed) instead of the iOS Maps. You might want to use Google Maps app because it supports waypoints.|
+| `allowGoogleMapsWeb`| `boolean` | If waypoints are passed in and Google Maps is not installed, you can either open Apple Maps and the first waypoint is used as the to-address (the rest is ignored), or you can set this option to `true` to open Google Maps on web so all waypoints are shown.|
+
+### AndroidOptions
+| Name| Type | Description|
+|-----|------|------------|
+| `newTask` | `boolean` | _Optional_: Indicates whether to start directions as new task.|
 
 ## License
 
