[04/12] git commit: updated doc for w3c alignment

[ld...@apache.org]

updated doc for w3c alignment


Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration/commit/2098047f
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration/tree/2098047f
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration/diff/2098047f

Branch: refs/heads/master
Commit: 2098047fb4a7cf5b1b30fdd6b267850e20692d71
Parents: 07f5c90
Author: Edna Morales <ed...@ednas-mbp-2.raleigh.ibm.com>
Authored: Tue Jul 22 14:03:23 2014 -0400
Committer: Edna Morales <ed...@ednas-mbp-2.raleigh.ibm.com>
Committed: Tue Jul 22 14:03:23 2014 -0400

----------------------------------------------------------------------
 doc/index.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 64 insertions(+), 3 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration/blob/2098047f/doc/index.md
----------------------------------------------------------------------
diff --git a/doc/index.md b/doc/index.md
index c517ce5..20cede8 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -27,6 +27,7 @@ This plugin provides a way to vibrate the device.
 
 ## Supported Platforms
 
+navigator.vibrate<br />
 navigator.notification.vibrate
 - Amazon Fire OS
 - Android
@@ -38,7 +39,65 @@ navigator.notification.vibrate
 navigator.notification.vibrateWithPattern,<br />navigator.notification.cancelVibration
 - Android
 
-## notification.vibrate
+## vibrate (recommended)
+
+This function has three different functionalities based on parameters passed to it.
+
+###Standard vibrate
+
+Vibrates the device for a given amount of time.
+
+    navigator.vibrate(time)
+
+-__time__: Milliseconds to vibrate the device. _(Number)_
+
+####Example
+
+    // Vibrate for 3 seconds
+    navigator.vibrate(3000);
+
+####iOS Quirks
+
+- __time__: Ignores the specified time and vibrates for a pre-set amount of time.
+
+    navigator.vibrate(3000);   // 3000 is ignored
+
+####Windows and Blackberry Quirks
+
+- __time__: Max time is 5000ms (5s)
+
+    navigator.vibrate(8000);  // will be truncated to 5000
+
+###Vibrate with a pattern (Android only)
+
+Vibrates the device with a given pattern.
+
+    navigator.vibrate(pattern)
+
+- __pattern__: Sequence of durations (in milliseconds) for which to turn on or off the vibrator. _(Array of Numbers)_
+
+####Example
+
+    // Vibrate for 1 second
+    // Wait for 1 second
+    // Vibrate for 3 seconds
+    // Wait for 1 second
+    // Vibrate for 5 seconds
+    navigator.vibrate([1000, 1000, 3000, 1000, 5000]);
+
+###Cancel vibration (not supported in iOS)
+
+Immediately cancels any currently running vibration.
+
+    navigator.vibrate(0)
+
+or
+
+    navigator.vibrate([])
+
+Passing in a parameter of 0 or an empty array will cancel any vibrations.
+
+## *notification.vibrate (deprecated)
 
 Vibrates the device for a given amount of time.
 
@@ -58,7 +117,7 @@ Vibrates the device for a given amount of time.
         navigator.notification.vibrate();
         navigator.notification.vibrate(2500);   // 2500 is ignored
 
-## notification.vibrateWithPattern
+## *notification.vibrateWithPattern (deprecated)
 
 Vibrates the device with a given pattern.
 
@@ -80,8 +139,10 @@ Vibrates the device with a given pattern.
     // (do not repeat)
     navigator.notification.vibrateWithPattern([0, 100, 100, 200, 100, 400, 100, 800]);
 
-## notification.cancelVibration
+## *notification.cancelVibration (deprecated)
 
 Immediately cancels any currently running vibration.
 
     navigator.notification.cancelVibration()
+
+*Note - due to alignment with w3c spec, the starred methods will be phased out