Clean up some comments and formatting

inc/timdac_ll.h

@@ -20,7 +20,7 @@
 // Diagnostic info struct. If TIMDAC_DIAGNOSTIC is defined nonzero, this is the
 // struct that timdac_ll_diagnostic() will fill.
 typedef struct timdac_lldiag_s {
-	// Total number of calibration cycles run (will overflow)
+	// Total number of tuning cycles run (will overflow)
 	uint16_t cycles;
 
 	// Tuning clobber counter.

src/timdac.c

@@ -96,7 +96,7 @@ void timdac_poll(void)
 
 	if (_count >= TIMDAC_TUNE_INTERVAL || !timdac_ll_tuned())
 	{
-		// Reached the end, time to calibrate
+		// Reached the end, time to tune
 		_count = 0;
 		if (timdac_ll_tune())
 			return;

src/timdac_ll.c

@@ -38,10 +38,15 @@ static timdac_lldiag_t _diag;
 // Compute the tuned compare value for a given DAC code
 static uint16_t _compare_for_value(uint16_t value);
 
-// Start the external hardware cycle for the current state
+// Start the external hardware cycle for the current state. Note the timer
+// behavior: in STATE_IDLE, _select() will never start the timer; in other
+// states, it will always start the timer.
 static void _select(void);
 
-// Perform one step of the tuning SAR binary search
+// Perform one step of the tuning SAR binary search by moving _tune_sar_top
+// and _tune_sar_bot as appropriate. This function does not perform the
+// computation to adjust _tune afterward; that is handled by timdac_ll_tune()
+// to keep the more long-winded arithmetic out of ISR context.
 static void _sar_search(void);
 
 void timdac_ll_init(void)
@@ -54,10 +59,10 @@ void timdac_ll_init(void)
 	_tune_sar_bot = 0;
 
 #if TIMDAC_DIAGNOSTIC
-	_diag.cycles = 0;
+	_diag.cycles   = 0;
 	_diag.clobbers = 0;
-	_diag.noise = 0;
-	_diag.tune = 0;
+	_diag.noise    = 0;
+	_diag.tune     = 0;
 #endif
 
 	timdac_hw_init();
@@ -236,6 +241,11 @@ void timdac_ll_diagnostic(timdac_lldiag_t * diag)
 static uint16_t _compare_for_value(uint16_t value)
 {
 	// Scale value according to tuning, with rounding.
+	//
+	// WARNING: This can affect DNL! The rounding method used can shift
+	// the DNL plot up or down slightly around zero, which changes the
+	// maximum value. This method centers it the best for lowest DNL. Do
+	// not change without testing!
 	return (value * (_tune / UINT16_MAX) + 16384) / 32768;
 }