Add Clock docs

README.md

@@ -186,6 +186,46 @@ More specifically:
 
 If in doubt, please contact [devsupport@getpebble.com](mailto:devsupport@getpebble.com).
 
+## Clock
+
+The Clock module makes working with the Wakeup module with time utility functions.
+
+### Clock
+
+`Clock` provides a single module of the same name `Clock`.
+
+````js
+var Clock = require('clock');
+````
+
+<a id="clock-weekday"></a>
+#### Clock.weekday(weekday, hour, minute[, seconds])
+[Clock.weekday]: #clock-weekday
+
+Calculates the seconds since the epoch until the next nearest moment of the given weekday and time parameters. `weekday` can either be a string representation of the weekday name such as `sunday`, or the 0-based index number, such as 0 for sunday. `hour` is a number 0-23 with 0-12 indicating the morning or a.m. times. `minute` and `seconds` numbers 0-59. `seconds` is optional.
+
+The weekday is always the next occurrence and is not limited by the current week. For example, if today is Wednesday, and `'tuesday'` is given for `weekday`, the resulting time will be referring to Tuesday of next week at least 5 days from now. Similarly, if today is Wednesday and `'Thursday'` is given, the time will be referring to tomorrow, the Thursday of the same week, between 0 to 2 days from now. This is useful for specifying the time for [Wakeup.schedule].
+
+````js
+// Next Tuesday at 6:00 a.m.
+var nextTime = Clock.weekday('tuesday', 6, 0);
+console.log('Seconds until then: ' + (nextTime - Date.now()));
+
+var Wakeup = require('wakeup');
+
+// Schedule a wakeup event.
+Wakeup.schedule(
+  { time: nextTime },
+  function(e) {
+    if (e.failed) {
+      console.log('Wakeup set failed: ' + e.error);
+    } else {
+      console.log('Wakeup set! Event ID: ' + e.id);
+    }
+  }
+)
+````
+
 ## Settings
 
 The Settings module allows you to add a configurable web view to your application and share options with it. Settings also provides two data accessors `Settings.option` and `Settings.data` which are backed by localStorage. Data stored in `Settings.option` is automatically shared with the configurable web view.
@@ -1055,10 +1095,12 @@ var Wakeup = require('wakeup');
 
 <a id="wakeup-schedule"></a>
 #### Wakeup.schedule(options, callback(event))
-[Wakeup.schedule]: #wakeup.schedule
+[Wakeup.schedule]: #wakeup-schedule
 
 Schedules a wakeup event that will wake up the app at the specified time. `callback` will be immediately called asynchronously with whether the wakeup event was successfully set or not. Wakeup events cannot be scheduled within one minute of each other regardless of what app scheduled them. Each app may only schedule up to 8 wakeup events.
 
+See [Clock.weekday] for setting wakeup events at particular times of a weekday.
+
 ````js
 Wakeup.schedule(
   {
@@ -1070,7 +1112,7 @@ Wakeup.schedule(
   function(e) {
     if (e.failed) {
       // Log the error reason
-      console.log('Wakeup failed: ' + e.error + '!');
+      console.log('Wakeup set failed: ' + e.error);
     } else {
       console.log('Wakeup set! Event ID: ' + e.id);
     }
@@ -1239,6 +1281,7 @@ For more information, see [Vector2 in the three.js reference documentation][thre
 [Using Images]: #using-images
 [Using Fonts]: #using-fonts
 
+[Clock]: #clock
 [Window]: #window
 [Card]: #card
 [Menu]: #menu