more tempo documentation.

2 files changed, 17 insertions, 4 deletions

diff --git a/libs/ardour/ardour/tempo.h b/libs/ardour/ardour/tempo.h
index 57c6ced275..1b587a5668 100644
--- a/libs/ardour/ardour/tempo.h
+++ b/libs/ardour/ardour/tempo.h
@@ -441,6 +441,7 @@ class LIBARDOUR_API TempoMap : public PBD::StatefulDestructible
 	Evoral::Beats framewalk_to_qn (framepos_t pos, framecnt_t distance) const;
 
 	/* quarter note related functions are also tempo-sensitive and ignore meter.
+	   quarter notes may be compared with and assigned to Evoral::Beats.
 	*/
 	double quarter_note_at_frame (const framepos_t frame);
 	double quarter_note_at_frame_rt (const framepos_t frame);
@@ -451,6 +452,7 @@ class LIBARDOUR_API TempoMap : public PBD::StatefulDestructible
 	double quarter_note_at_beat (const double beat);
 	double beat_at_quarter_note (const double beat);
 
+	/* obtain a musical subdivision via a frame position and magic note divisor.*/
 	double exact_qn_at_frame (const framepos_t& frame, const int32_t sub_num);
 	double exact_beat_at_frame (const framepos_t& frame, const int32_t sub_num);
 
diff --git a/libs/ardour/tempo.cc b/libs/ardour/tempo.cc
index 073e0dc0a8..a5e7defce0 100644
--- a/libs/ardour/tempo.cc
+++ b/libs/ardour/tempo.cc
@@ -3320,6 +3320,7 @@ TempoMap::gui_dilate_tempo (TempoSection* ts, const framepos_t& frame, const fra
 
 /** Returns the exact bbt-based beat corresponding to the bar, beat or quarter note subdivision nearest to
  * the supplied frame, possibly returning a negative value.
+ *
  * @param frame  The session frame position.
  * @param sub_num The subdivision to use when rounding the beat.
  *                A value of -1 indicates rounding to BBT bar. 1 indicates rounding to BBT beats.
@@ -3327,11 +3328,17 @@ TempoMap::gui_dilate_tempo (TempoSection* ts, const framepos_t& frame, const fra
  *                0 indicates that the returned beat should not be rounded (equivalent to quarter_note_at_frame()).
  * @return The beat position of the supplied frame.
  *
+ * when working to a musical grid, the use of sub_nom indicates that
+ * the position should be interpreted musically.
+ *
+ * it effectively snaps to meter bars, meter beats or quarter note divisions
+ * (as per current gui convention) and returns a musical position independent of frame rate.
+ *
  * If the supplied frame lies before the first meter, the return will be negative,
  * in which case the returned beat uses the first meter (for BBT subdivisions) and
  * the continuation of the tempo curve (backwards).
  *
- * This function uses both tempo and meter.
+ * This function is sensitive to tempo and meter.
  */
 double
 TempoMap::exact_beat_at_frame (const framepos_t& frame, const int32_t sub_num)
@@ -3349,8 +3356,6 @@ TempoMap::exact_beat_at_frame_locked (const Metrics& metrics, const framepos_t&
 
 /** Returns the exact quarter note corresponding to the bar, beat or quarter note subdivision nearest to
  * the supplied frame, possibly returning a negative value.
- * Supplying a frame position with a non-zero sub_num is equivalent to supplying
- * a quarter-note musical position without frame rounding (see below)
  *
  * @param frame  The session frame position.
  * @param sub_num The subdivision to use when rounding the quarter note.
@@ -3359,11 +3364,17 @@ TempoMap::exact_beat_at_frame_locked (const Metrics& metrics, const framepos_t&
  *                0 indicates that the returned quarter note should not be rounded (equivalent to quarter_note_at_frame()).
  * @return The quarter note position of the supplied frame.
  *
+ * When working to a musical grid, the use of sub_nom indicates that
+ * the frame position should be interpreted musically.
+ *
+ * it effectively snaps to meter bars, meter beats or quarter note divisions
+ * (as per current gui convention) and returns a musical position independent of frame rate.
+ *
  * If the supplied frame lies before the first meter, the return will be negative,
  * in which case the returned quarter note uses the first meter (for BBT subdivisions) and
  * the continuation of the tempo curve (backwards).
  *
- * This function uses both tempo and meter.
+ * This function is tempo-sensitive.
  */
 double
 TempoMap::exact_qn_at_frame (const framepos_t& frame, const int32_t sub_num)