comparison base/generics.lisp @ 123:f57ab0e109fb

More docs

darcs-hash:20070730133825-f76cc-ca46fd2ec43676a919ecf67efa80a7881013f405.gz

 (cl:in-package #:amuse) 
 
 ;;; Pulling compositions from the database 
 
-(defgeneric get-composition (identifier))
+(defgeneric get-composition (identifier)
+  (:documentation "Returns a composition of type dependant on
+  identifier"))
 
 (defgeneric monody (object)
   (:documentation "Returns a monody."))
 (defgeneric ensure-monody (object)
   (:documentation "Returns a generalised boolean."))

   (:method (p) (mod (midi-pitch-number p) 12)))
 (defgeneric span (pitch-interval-designator))
 
 ;; time
 
-(defgeneric duration (period-designator))
-(defgeneric (setf duration) (value period-designator))
-(defgeneric timepoint (moment-designator))
-(defgeneric (setf timepoint) (value moment-designator))
+(defgeneric duration (period-designator)
+  (:documentation "Returns a value. Probably should only apply do
+  periods (rather than designators?)"))
+(defgeneric (setf duration) (value period-designator)
+  (:documentation "As with duration, should probably work only
+  with periods"))
+(defgeneric timepoint (moment-designator)
+  (:documentation "Returns a value for a moment. Does this make
+  any sense on a designator?"))
+(defgeneric (setf timepoint) (value moment-designator)
+  (:documentation "Sets timepoint. What does this mean for a
+  designator?"))
 (defgeneric cut-off (anchored-period-designator) ; name?
   (:documentation "Returns a <moment> representing the point at
   which the anchored period has ended. By default, is calculated
   as the result of running time+ on the onset and period of the
   object.")

 ;; 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
 ;; its meaning is clear. beat-units-per-bar is clearer, though, I
 ;; think.
 
-(defgeneric beat-units-per-bar (time-signature))
+(defgeneric beat-units-per-bar (time-signature)
+  (:documentation "In a standard, fraction-like time-signature or
+  a symbolic equivalent, this is the numerator."))
 (defgeneric time-signature-numerator (time-signature)
-  (:method (ts) (beat-units-per-bar ts)))
-(defgeneric beat-units (time-signature))
+  (:method (ts) (beat-units-per-bar ts))
+  (:documentation "Not obviously meaningful for non fraction-like
+  time signatures"))
+(defgeneric beat-units (time-signature)
+  (:documentation "In a standard, fraction-like time-signature or
+  a symbolic equivalent, this is the numerator (n.b.,
+  tactus-duration is the method of choice for compound time
+  sensitive queries."))
 (defgeneric time-signature-denominator (time-signature)
-  (:method (ts) (beat-units ts)))
+  (:method (ts) (beat-units ts))
+  (:documentation "Not obviously meaningful for non fraction-like
+  time signatures"))
 (defgeneric tactus-duration (time-signature)
   ;; basic, but should do?
   (:method (ts)
     (cond
       ((and (not (= (beat-units-per-bar ts) 3))
 	    (= (rem (beat-units-per-bar ts) 3) 0))
        ;; compound time
        (* (/ 4 (beat-units ts))
 	  3))
-      (t (/ 4 (beat-units ts))))))
-
-(defgeneric key-signature-sharps (key-signature))
-(defgeneric key-signature-mode (ks))
-
-(defgeneric bpm (tempo)) ;; in bpm
+      (t (/ 4 (beat-units ts)))))
+  (:documentation "Returns a number of crotchets to represent the
+  tactus, based on some idea of time signature patterns. Should,
+  in future, return a duration rather than a number."))
+
+(defgeneric key-signature-sharps (key-signature)
+  (:documentation "Simple query for normal key-signatures."))
+(defgeneric key-signature-mode (ks)
+  (:documentation "Query that only makes sense for midi-like key
+  signatures"))
+
+(defgeneric bpm (tempo)
+  (:documentation "Basic tempo query")) ;; in bpm
 (defgeneric microseconds-per-crotchet (tempo)
   ;; As used (when rounded) in MIDI
-  (:method (tp) (/ 60000000 (bpm tp))))
+  (:method (tp) (/ 60000000 (bpm tp)))
+  (:documentation "Basic tempo query for MIDI. N.B. This will be
+  a fraction and must be rounded before being used for output."))
 
 ;;; Coerce-type accessors
 
 ;; Should I be including these default methods?  Should the accessors
 ;; be direct slot accessors or the generics I'm using? Should we
 ;; return the object itself if it already is in the target class?
 
 (defgeneric anchored-period (anchored-period-designator)
-  (:method (apd) (make-anchored-period (onset apd) (duration apd))))
+  (:method (apd) (make-anchored-period (onset apd) (duration apd)))
+  (:documentation "Coerce any anchored period to a plain anchored
+  period"))
 
 (defgeneric floating-period (period-designator)
-  (:method (pd) (make-floating-period (duration pd))))
+  (:method (pd) (make-floating-period (duration pd)))
+  (:documentation "Coerce any period to a floating period"))
 
 (defgeneric moment (moment-designator)
-  (:method (md) (make-moment (timepoint md))))
+  (:method (md) (make-moment (timepoint md)))
+  (:documentation "Coerce any moment(-designator?), including an
+  anchored-period to a moment"))
 
 (defgeneric onset (anchored-period-designator)
-  (:method (apd) (moment apd)))
+  (:method (apd) (moment apd))
+  (:documentation "Return a moment for the start of an anchored period"))
 (defgeneric (setf onset) (value anchored-period-designator))
 
 ;;; Time Protocol (or moments?)
 
 ;; negative times/durations -> ERROR? 

 
 
 ;;; Time Signature 
 
 (defgeneric get-applicable-time-signatures (anchored-period composition)
-  (:method (ap c) (find-overlapping ap (time-signatures c))))
-
-(defgeneric time-signature-equal (ts1 ts2))
+  (:method (ap c) (find-overlapping ap (time-signatures c)))
+  (:documentation "Return a list of time-signatures that are
+  relevant to <anchored-period>. The period may contain
+  information such as staff position and voicing, and the method
+  may use this to filter its response"))
+
+(defgeneric time-signature-equal (ts1 ts2)
+  (:documentation "Comparison operator. The definition of
+  equality is left open for implementers"))
 
 ;;; Tempo 
 
 (defgeneric get-applicable-tempi  (anchored-period composition)
-  (:method (ap c) (find-overlapping ap (tempi c))))
-
-(defgeneric tempo-equal (t1 t2))
+  (:method (ap c) (find-overlapping ap (tempi c)))
+  (:documentation "Return a list of tempi that are relevant to
+  <anchored-period>. The period may contain information such as
+  staff position and voicing, and the method may use this to
+  filter its response"))
+
+(defgeneric tempo-equal (t1 t2)
+  (:documentation "Comparison operator. The definition of
+  equality is left open for implementers"))
 
 ;;; Tonality (Key Signature / Mode) 
 
-(defgeneric get-applicable-key-signatures (object1 object2))
-
-(defgeneric key-signature-equal (ks1 ks2))
+(defgeneric get-applicable-key-signatures (object1 object2)
+  (:documentation "Return a list of key-signatures that are
+  relevant to <anchored-period>. The period may contain
+  information such as staff position and voicing, and the method
+  may use this to filter its response"))
+
+(defgeneric key-signature-equal (ks1 ks2)
+  (:documentation "Comparison operator. The definition of
+  equality is left open to implementers"))
 
 ;;; Dynamics 
 ;;; Voice 
 ;;; Boundary Strength (phrasing)