diff utils/utils.lisp @ 134:5e362d998f29

More documentation

darcs-hash:20070828101524-f76cc-6add2c3c254befc3cf767ac69706865b7830bc6a.gz

--- a/utils/utils.lisp	Tue Aug 21 12:03:38 2007 +0100
+++ b/utils/utils.lisp	Tue Aug 28 11:15:24 2007 +0100
@@ -11,7 +11,12 @@
   (:method (e) (not (pitchedp e))))
 
 ;; Rhythm methods
-(defgeneric crotchets-in-a-bar (time-signature))
+(defgeneric crotchets-in-a-bar (time-signature)
+  (:documentation "Convenient function for finding the number of
+  crotchet beats in a bar based on the provided
+  time-signature. It should be borne in mind that this needn't be
+  an integer - a time signature of 3/8, for example, should yield
+  an answer of 3/2"))
 (defmethod crotchets-in-a-bar ((time-signature basic-time-signature))
   (let ((num (time-signature-numerator time-signature))
 	(den (time-signature-denominator time-signature)))
@@ -39,8 +44,17 @@
 ;; Not as simple as it seems - have to take into account numbering
 ;; practices and leading silences in representations where bar number
 ;; isn't part of the explicit structure.
-(defgeneric bar-number (moment composition))
-(defgeneric bar-onset (bar-number composition))
+(defgeneric bar-number (moment composition)
+  (:documentation "Returns the bar number of moment in
+  composition. N.B. Although this will be a designated value in
+  some, particularly score-based, implementations, it will be a
+  derived value in others, particularly midi, where it may be
+  necessary to take into account numbering practices and leading
+  silences."))
+(defgeneric bar-onset (bar-number composition)
+  (:documentation "Returns a moment for the beginning of the bar
+  with the given bar-number. Cautions about bar numbering as
+  given in the bar-number documentation apply here also."))
 
 (defgeneric bass-note (anchored-period composition))