From 6b85054e35d19d74414580e453b6f927ed7967d0 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Sun, 15 Sep 2013 22:20:39 -0400 Subject: Clean up docstrings for agenda module. --- 2d/agenda.scm | 61 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 30 insertions(+), 31 deletions(-) (limited to '2d') 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*)) -- cgit v1.2.3