better alarms docs

diff --git a/basis/alarms/alarms-docs.factor b/basis/alarms/alarms-docs.factor
index 82134e825ea1320da202a2069d254212904bbdd5..df88f497016bf9b841c67732f7900663ced17111 100644 (file)
--- a/basis/alarms/alarms-docs.factor
+++ b/basis/alarms/alarms-docs.factor
@@ -1,16 +1,23 @@
-IN: alarms\r
 USING: help.markup help.syntax calendar quotations ;\r
+IN: alarms\r
 \r
 HELP: alarm\r
 { $class-description "An alarm. Can be passed to " { $link cancel-alarm } "." } ;\r
 \r
 HELP: add-alarm\r
 { $values { "quot" quotation } { "time" timestamp } { "frequency" { $maybe duration } } { "alarm" alarm } }\r
-{ $description "Creates and registers an alarm. If " { $snippet "frequency" } " is " { $link f } ", this will be a one-time alarm, otherwise it will fire with the given frequency. The quotation will be called from the alarm thread." } ;\r
+{ $description "Creates and registers an alarm to start at " { $snippet "time" } ". If " { $snippet "frequency" } " is " { $link f } ", this will be a one-time alarm, otherwise it will fire with the given frequency. The quotation will be called from the alarm thread." } ;\r
 \r
 HELP: later\r
 { $values { "quot" quotation } { "duration" duration } { "alarm" alarm } }\r
-{ $description "Creates and registers an alarm which calls the quotation once at " { $snippet "time" } " from now." } ;\r
+{ $description "Creates and registers an alarm which calls the quotation once at " { $snippet "time" } " from now." }\r
+{ $examples\r
+    { $unchecked-example\r
+        "USING: alarms io calendar ;"\r
+        """[ "GET BACK TO WORK, Guy." print flush ] 10 minutes later drop"""\r
+        ""\r
+    }\r
+} ;\r
 \r
 HELP: cancel-alarm\r
 { $values { "alarm" alarm } }\r
@@ -20,16 +27,29 @@ HELP: every
 { $values\r
      { "quot" quotation } { "duration" duration }\r
      { "alarm" alarm } }\r
-{ $description "Creates and registers an alarm which calls the quotation repeatedly, using " { $snippet "dt" } " as the frequency." } ;\r
+{ $description "Creates and registers an alarm which calls the quotation repeatedly, using " { $snippet "dt" } " as the frequency." }\r
+{ $examples\r
+    { $unchecked-example\r
+        "USING: alarms io calendar ;"\r
+        """[ "Hi Buddy." print flush ] 10 seconds every drop"""\r
+        ""\r
+    }\r
+} ;\r
 \r
 ARTICLE: "alarms" "Alarms"\r
-"The " { $vocab-link "alarms" } " vocabulary provides a lightweight way to schedule one-time and recurring tasks without spawning a new thread."\r
+"The " { $vocab-link "alarms" } " vocabulary provides a lightweight way to schedule one-time and recurring tasks without spawning a new thread." $nl\r
+"The alarm class:"\r
 { $subsections\r
     alarm\r
-    add-alarm\r
-    later\r
-    cancel-alarm\r
 }\r
+"Register a recurring alarm:"\r
+{ $subsections every }\r
+"Register a one-time alarm:"\r
+{ $subsections later }\r
+"Low-level interface to add alarms:"\r
+{ $subsections add-alarm }\r
+"Cancelling an alarm:"\r
+{ $subsections cancel-alarm }\r
 "Alarms do not persist across image saves. Saving and restoring an image has the effect of calling " { $link cancel-alarm } " on all " { $link alarm } " instances." ;\r
 \r
 ABOUT: "alarms"\r