summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Thompson <dthompson@member.fsf.org>2013-09-15 22:20:39 -0400
committerDavid Thompson <dthompson@member.fsf.org>2013-09-15 22:20:39 -0400
commit6b85054e35d19d74414580e453b6f927ed7967d0 (patch)
tree7d772d3ae1993179eb932ae8165d5f18bbbb2470
parent97b873c0aaf143f06949e039782bc6c82b558d5d (diff)
Clean up docstrings for agenda module.
-rw-r--r--2d/agenda.scm61
1 files changed, 30 insertions, 31 deletions
diff --git a/2d/agenda.scm b/2d/agenda.scm
index 6e9f61d..77983b2 100644
--- a/2d/agenda.scm
+++ b/2d/agenda.scm
@@ -46,15 +46,15 @@
(queue segment-queue))
(define (make-time-segment time . callbacks)
- "Constructs a new time segment with given time and enqueus all
-callback procedures."
+ "Create a new time segment at TIME and enqueus everything in the
+list CALLBACKS."
(let ((segment (%make-time-segment time (make-q))))
;; Enqueue all callbacks
(for-each (lambda (c) (segment-enq segment c)) callbacks)
segment))
(define (segment-enq segment callback)
- "Enqueues a callback procedure onto the segment queue."
+ "Add the CALLBACK procedure to SEGMENT's queue."
(enq! (segment-queue segment) callback))
;;;
@@ -68,7 +68,7 @@ callback procedures."
(segments agenda-segments set-agenda-segments!))
(define (make-agenda)
- "Creates a new empty agenda."
+ "Create a new, empty agenda."
(%make-agenda 0 '()))
;; The global agenda that will be used when schedule is called outside
@@ -86,49 +86,48 @@ callback procedures."
(set! *current-agenda* global-agenda)))
(define (agenda-empty? agenda)
- "Returns #t if agenda has no scheduled procedures."
+ "Return #t if AGENDA has no scheduled procedures."
(null? (agenda-segments agenda)))
(define (first-segment agenda)
- "Returns the first time segment in the agenda."
+ "Return the first time segment in AGENDA."
(car (agenda-segments agenda)))
(define (rest-segments agenda)
- "Returns everything but the first segment in the agenda."
+ "Return everything but the first segment in AGENDA."
(cdr (agenda-segments agenda)))
(define (agenda-add-segment agenda time callback)
- "Adds a new time segment to the beginning of the agenda and enqueues
-the given callback."
- (set-agenda-segments! agenda (cons (make-time-segment time callback)
- (agenda-segments agenda))))
+ "Add a new time segment to the beginning of AGENDA at the given TIME
+and enqueue CALLBACK."
+ (set-agenda-segments! agenda
+ (cons (make-time-segment time callback)
+ (agenda-segments agenda))))
(define (insert-segment segments time callback)
- "Inserts a new segment after the first segment in the list."
- (set-cdr! segments (cons (make-time-segment time callback) (cdr segments))))
+ "Insert a new time segment after the first segment in SEGMENTS."
+ (set-cdr! segments
+ (cons (make-time-segment time callback)
+ (cdr segments))))
(define (first-agenda-item agenda)
- "Returns the first time segment queue in the agenda."
+ "Return the first time segment queue in AGENDA."
(if (agenda-empty? agenda)
(error "Agenda is empty")
(segment-queue (first-segment agenda))))
(define (agenda-time-delay agenda dt)
- "Returns time given a delta from the current agenda time."
+ "Return the sum of the time delta, DT, and the current time of AGENDA."
(+ (agenda-time agenda) (inexact->exact (round dt))))
(define (%agenda-schedule agenda callback dt)
- "Schedules a callback procedure in the agenda relative to the
-current agenda time."
+ "Schedule the procedure CALLBACK in AGENDA to be run DT updates from now."
(let ((time (agenda-time-delay agenda dt)))
(define (belongs-before? segments)
- "Determines if the time segment belongs before the first segment
-in the list"
(or (null? segments)
(< time (segment-time (car segments)))))
(define (add-to-segments segments)
- "Schedules callback in the proper place."
;; Add to existing time segment if the times match
(if (= (segment-time (car segments)) time)
(segment-enq (car segments) callback)
@@ -148,13 +147,13 @@ in the list"
(add-to-segments (agenda-segments agenda)))))
(define (flush-queue! q)
- "Dequeues and executes every element of q."
+ "Dequeue and execute every member of Q."
(unless (q-empty? q)
((deq! q)) ;; Execute scheduled procedure
(flush-queue! q)))
(define (%update-agenda agenda)
- "Moves agenda forward in time and run scheduled procedures."
+ "Move AGENDA forward in time and run scheduled procedures."
(set-agenda-time! agenda (1+ (agenda-time agenda)))
(let next-segment ()
(unless (agenda-empty? agenda)
@@ -167,19 +166,19 @@ in the list"
(next-segment))))))
(define (%clear-agenda agenda)
- "Removes all scheduled procedures from the agenda."
+ "Remove all scheduled procedures from AGENDA."
(set-agenda-segments! agenda '()))
(define* (agenda-schedule thunk #:optional (delay 1))
- "Schedules THUNK in the current agenda to run after DELAY
-updates (1 by default)."
+ "Schedule THUNK in the current agenda to run after DELAY updates (1
+by default)."
(%agenda-schedule *current-agenda* thunk delay))
(define* (agenda-schedule-interval thunk #:optional (interval 1) (delay 1))
- "Schedules THUNK in the current agenda to run after DELAY updates
-and run every INTERVAL updates thereafter. Both DELAY and INTERVAL
-default to 1. Simply pass THUNK and nothing else to schedule THUNK to
-be run upon every update."
+ "Schedule THUNK in the current agenda to run after DELAY updates and
+run every INTERVAL updates thereafter. Both DELAY and INTERVAL default
+to 1. Simply pass THUNK and nothing else to schedule THUNK to be run
+upon every update."
(%agenda-schedule *current-agenda*
(lambda ()
(thunk)
@@ -187,9 +186,9 @@ be run upon every update."
delay))
(define (update-agenda)
- "Updates the current agenda."
+ "Update the current agenda."
(%update-agenda *current-agenda*))
(define (clear-agenda)
- "Clears the current agenda."
+ "Clear the current agenda."
(%clear-agenda *current-agenda*))