From a3e104f8e2344d33f88a779901a11f7cce5add26 Mon Sep 17 00:00:00 2001
From: Thomas Harte <thomas.harte@gmail.com>
Date: Tue, 13 Feb 2024 13:46:27 -0500
Subject: [PATCH] Clean up commentary.

---
 Components/AY38910/AY38910.cpp | 23 ++++++++++++++---------
 Components/AY38910/AY38910.hpp |  7 +++++--
 2 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/Components/AY38910/AY38910.cpp b/Components/AY38910/AY38910.cpp
index 3fa8462e1..c32df440e 100644
--- a/Components/AY38910/AY38910.cpp
+++ b/Components/AY38910/AY38910.cpp
@@ -12,6 +12,15 @@
 
 using namespace GI::AY38910;
 
+// Note on dividers: the real AY has a built-in divider of 8
+// prior to applying its tone and noise dividers. But the YM fills the
+// same total periods for noise and tone with double-precision envelopes.
+// Therefore this class implements a divider of 4 and doubles the tone
+// and noise periods. The envelope ticks along at the divide-by-four rate,
+// but if this is an AY rather than a YM then its lowest bit is forced to 1,
+// matching the YM datasheet's depiction of envelope level 31 as equal to
+// programmatic volume 15, envelope level 29 as equal to programmatic 14, etc.
+
 template <bool is_stereo>
 AY38910SampleSource<is_stereo>::AY38910SampleSource(Personality personality, Concurrency::AsyncTaskQueue<false> &task_queue) : task_queue_(task_queue) {
 	// Don't use the low bit of the envelope position if this is an AY.
@@ -101,15 +110,6 @@ void AY38910SampleSource<is_stereo>::set_output_mixing(float a_left, float b_lef
 	c_right_ = uint8_t(c_right * 255.0f);
 }
 
-	// Note on structure below: the real AY has a built-in divider of 8
-	// prior to applying its tone and noise dividers. But the YM fills the
-	// same total periods for noise and tone with double-precision envelopes.
-	// Therefore this class implements a divider of 4 and doubles the tone
-	// and noise periods. The envelope ticks along at the divide-by-four rate,
-	// but if this is an AY rather than a YM then its lowest bit is forced to 1,
-	// matching the YM datasheet's depiction of envelope level 31 as equal to
-	// programmatic volume 15, envelope level 29 as equal to programmatic 14, etc.
-
 template <bool is_stereo>
 void AY38910SampleSource<is_stereo>::advance() {
 	const auto step_channel = [&](int c) {
@@ -391,3 +391,8 @@ void AY38910SampleSource<is_stereo>::update_bus() {
 // Ensure both mono and stereo versions of the AY are built.
 template class GI::AY38910::AY38910SampleSource<true>;
 template class GI::AY38910::AY38910SampleSource<false>;
+
+// Perform an explicit instantiation of the BufferSource to hope for
+// appropriate inlining of advance() and level().
+template struct GI::AY38910::AY38910<true>;
+template struct GI::AY38910::AY38910<false>;
diff --git a/Components/AY38910/AY38910.hpp b/Components/AY38910/AY38910.hpp
index 3d82d4f3f..3e951bbad 100644
--- a/Components/AY38910/AY38910.hpp
+++ b/Components/AY38910/AY38910.hpp
@@ -164,8 +164,11 @@ template <bool stereo> class AY38910SampleSource {
 		friend struct State;
 };
 
-/// Define a default AY to be the sample source with a master divider of 4;
-/// real AYs have a divide-by-8 step built in but YMs have only a divide-by-4,
+/// Defines a default AY to be the sample source with a master divider of 4;
+/// real AYs have a divide-by-8 step built in but YMs apply only a divide by 4.
+///
+/// The implementation of AY38910SampleSource combines those two worlds
+/// by always applying a divide by four and scaling other things as appropriate.
 template <bool stereo> struct AY38910:
 	public AY38910SampleSource<stereo>,
 	public Outputs::Speaker::SampleSource<AY38910<stereo>, stereo, 4> {