changeset 100:ad9cca28fecf

Added doc-strings

darcs-hash:20070725171218-f76cc-c62173b38861d7c368d5219cc743d85a4f67fda8.gz

--- a/base/classes.lisp	Tue Jul 24 16:07:30 2007 +0100
+++ b/base/classes.lisp	Wed Jul 25 18:12:18 2007 +0100
@@ -13,22 +13,32 @@
 ;; types of information-specifiers
 
 (defclass identifier () ()) ;; for composition specification
-(defclass moment-designator () ())
-(defclass period-designator () ())
-(defclass anchored-period-designator (moment-designator period-designator) ())
-(defclass pitch-designator () ())
-(defclass pitch-interval-designator () ())
+(defclass moment-designator () ()
+  (:documentation "Object indicating a point in time"))
+(defclass period-designator () ()
+  (:documentation "Object indicating a region of time"))
+(defclass anchored-period-designator (moment-designator period-designator) ()
+  (:documentation "Object indicating a region of time starting at
+  a specific point in time"))
+(defclass pitch-designator () ()
+  (:documentation "Object indicating some sort of pitch"))
+(defclass pitch-interval-designator () ()
+  (:documentation "Object indicating a distance in pitch space"))
 
 ;; time-related classes
 
 (defclass moment (moment-designator) 
-  ((time :accessor %moment-time :initarg :time)))
+  ((time :accessor %moment-time :initarg :time))
+  (:documentation "A moment represented on a number line"))
 
 (defclass period (period-designator) 
-  ((interval :accessor %period-interval :initarg :interval)))
+  ((interval :accessor %period-interval :initarg :interval))
+  (:documentation "A number-line-based period"))
 
-(defclass floating-period (period) ())
-(defclass anchored-period (period moment anchored-period-designator) ())
+(defclass floating-period (period) ()
+  (:documentation "A simple numeric period"))
+(defclass anchored-period (period moment anchored-period-designator) ()
+  (:documentation "Number-line-based anchored period"))
 
 ;; pitch-related classes
 
@@ -36,7 +46,9 @@
 
 (defclass pitch (pitch-designator) ())
 (defclass chromatic-pitch (pitch) 
-  ((number :accessor %chromatic-pitch-number :initarg :number)))
+  ((number :accessor %chromatic-pitch-number :initarg :number))
+  (:documentation "A pitch represented as a number, with higher
+  values representing high pitches."))
 (defclass diatonic-pitch (pitch)
   ((name :accessor %diatonic-pitch-name :initarg :name)
    (accidental :accessor %diatonic-pitch-accidental :initarg :accidental)

--- a/base/generics.lisp	Tue Jul 24 16:07:30 2007 +0100
+++ b/base/generics.lisp	Wed Jul 25 18:12:18 2007 +0100
@@ -107,7 +107,7 @@
 ;; I've given the time-sig accessors general names because it allows
 ;; for symbols in time-signatures as well as numbers - numerator is an
 ;; odd accessor if the time sig is C (even in common practice) but
-;; it's meaning is clear. beat-units-per-bar is clearer, though, I
+;; its meaning is clear. beat-units-per-bar is clearer, though, I
 ;; think.
 
 (defgeneric beat-units-per-bar (time-signature))

--- a/base/methods.lisp	Tue Jul 24 16:07:30 2007 +0100
+++ b/base/methods.lisp	Wed Jul 25 18:12:18 2007 +0100
@@ -200,16 +200,24 @@
 ;; Time protocol
 
 (defmethod time+ ((object1 moment) (object2 period))
+  "(time+ <moment> <period>) -> <moment> Implemented as a
+straightforward summation."
   (make-moment (+ (timepoint object1) (duration object2))))
 
 (defmethod time+ ((object1 period) (object2 moment)) ;?
+  "(time+ <period> <moment>) -> <moment> Implemented as a
+straightforward summation."
   (time+ object2 object1))
 
 (defmethod time+ ((object1 period) (object2 period))
+  "(time+ <period> <period>) -> <period> Implemented as a
+straightforward summation."
   (make-floating-period (+ (duration object1)
 			   (duration object2))))
 
 (defmethod time+ ((object1 moment) (object2 moment))
+  "(time+ <moment> <moment>) -> <condition:undefined-action> The
+question makes no sense."
   (error 'undefined-action :operation 'time+ :datatype (list (class-of object1) (class-of object2))))
 
 (defmethod time- ((object1 moment) (object2 moment))

--- a/implementations/geerdes/methods.lisp	Tue Jul 24 16:07:30 2007 +0100
+++ b/implementations/geerdes/methods.lisp	Wed Jul 25 18:12:18 2007 +0100
@@ -4,12 +4,16 @@
 
 ;; identifiers
 (defun g-id (cat-id)
+  "Make a geerdes-identifier based on a catalogue id"
   (make-instance 'geerdes-identifier-cat-id :cat-id cat-id))
 (defun g-id-file-id (file-id)
+  "Make a geerdes-identifier based on a catalogue id"
   (make-instance 'geerdes-identifier-file-id :file-id file-id))
 
-(defgeneric cat-id (object))
-(defgeneric file-id (object))
+(defgeneric cat-id (object)
+  (:documentation "Return a catalogue id for object"))
+(defgeneric file-id (object)
+  (:documentation "Return a file id (unique db id) for object"))
 (defgeneric (setf cat-id) (value object))
 (defgeneric (setf file-id) (value object))