changeset 72:9960645779f0

Doc strings for some generics

darcs-hash:20070704142005-f76cc-247e963a3e68bc14c2a30c4c76bb569e07a4f8e6.gz

--- a/base/generics.lisp	Fri Jul 06 12:42:25 2007 +0100
+++ b/base/generics.lisp	Wed Jul 04 15:20:05 2007 +0100
@@ -6,12 +6,27 @@
 
 ;;; Getting constituents from compositions
 ;; IS this the mechanism we want to use
-(defgeneric time-signatures (composition))
-(defgeneric (setf time-signatures) (sequence composition))
-(defgeneric tempi (composition))
-(defgeneric (setf tempi) (sequence composition))
-(defgeneric key-signatures (composition))
-(defgeneric (setf key-signatures) (sequence composition))
+(defgeneric time-signatures (composition)
+  (:documentation "Returns all time-signatures in a composition
+  Probably shouldn't be exported - can be replaced
+  by (get-applicable-time-signature commposition composition)"))
+(defgeneric (setf time-signatures) (sequence composition)
+  (:documentation "Sets all time-signatures in a composition.
+  Is this wanted here?"))
+(defgeneric tempi (composition)
+  (:documentation "Returns all tempi in a composition Probably
+  shouldn't be exported - can be replaced
+  by (get-applicable-tempi commposition composition)"))
+(defgeneric (setf tempi) (sequence composition)
+  (:documentation "Sets all tempi in a composition.
+  Is this wanted here?"))
+(defgeneric key-signatures (composition)
+  (:documentation "Returns all key-signatures in a composition
+  Probably shouldn't be exported - can be replaced
+  by (get-applicable-key-signature commposition composition)"))
+(defgeneric (setf key-signatures) (sequence composition)
+  (:documentation "Sets all key sigs in a composition.
+  Is this wanted here?"))
 
 ;;; Simple Accessors
 
@@ -22,11 +37,22 @@
 (defgeneric chromatic-pitch (pitch-designator)) ; How simple are these
 (defgeneric diatonic-pitch (pitch-designator)) ; if has to be computed?
 (defgeneric frequency (object)) ;?
-(defgeneric midi-pitch-number (pitch-designator))
+(defgeneric midi-pitch-number (pitch-designator)
+  (:documentation "Takes a pitch-designator (usually a pitched
+  event) and returns an integer between 0 and 127 representing
+  the chromatic pitch designated (60=middle C, 48 the C below
+  that, etc.)"))
 (defgeneric meredith-chromatic-pitch-number (pitch-designator)
-  ;; David Meredith's PhD and ps13 code
+  (:documentation "Takes a pitch-designator (usually a pitched
+  event) and returns an integer representing the chromatic pitch
+  designated (39=middle C, 27 the C below that, etc.)")
+  ;; David Meredith's PhD and ps13 code. FIXME: What is the legal
+  ;; range of this?
   (:method (p) (- (midi-pitch-number p) 21)))
 (defgeneric pitch-class (pitch-designator)
+  (:documentation "Takes a pitch-designator (usually a pitched
+  event) and returns an integer between 0 and 12 representing
+  the octave-independant pitch, with c=0, c#=1, etc.")
   (:method (p) (mod (midi-pitch-number p) 12)))
 (defgeneric span (pitch-interval-designator))
 
@@ -37,6 +63,8 @@
 (defgeneric timepoint (moment-designator))
 (defgeneric (setf timepoint) (value moment-designator))
 (defgeneric cut-off (anchored-period-designator) ; name?
+  (:documentation "Returns a <moment> representing the point at
+  which the anchored period has ended.")
   (:method (apd) (time+ (moment apd) (floating-period apd))))
 
 ;; others