comparison base/generics.lisp @ 72:9960645779f0

Doc strings for some generics

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

 
 (defgeneric get-composition (identifier))
 
 ;;; 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
 
 ;; pitch-based
 
 (defgeneric pitch (object &key kind)) ; ? Maybe this returns the pitch
 				      ; in its ur form?
 (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))
 
 ;; time
 
 (defgeneric duration (period-designator))
 (defgeneric (setf duration) (value period-designator))
 (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
 
 ;; I've given the time-sig accessors general names because it allows