diff --git a/Components/AY38910/AY38910.hpp b/Components/AY38910/AY38910.hpp
index a43b9b6f5..e15f75f54 100644
--- a/Components/AY38910/AY38910.hpp
+++ b/Components/AY38910/AY38910.hpp
@@ -13,25 +13,44 @@
 
 namespace GI {
 
+/*!
+	Provides emulation of an AY-3-8910 / YM2149, which is a three-channel sound chip with a
+	noise generator and a volume envelope generator, which also provides two bidirectional
+	interface ports.
+*/
 class AY38910: public ::Outputs::Filter<AY38910> {
 	public:
+		/// Creates a new AY38910.
 		AY38910();
-		void set_clock_rate(double clock_rate);
 
-		void get_samples(unsigned int number_of_samples, int16_t *target);
-		void skip_samples(unsigned int number_of_samples);
+		/// Sets the clock rate at which this AY38910 will be run.
+		void set_clock_rate(double clock_rate);
 
 		enum ControlLines {
 			BC1		= (1 << 0),
 			BC2		= (1 << 1),
 			BCDIR	= (1 << 2)
 		};
+
+		/// Sets the value the AY would read from its data lines if it were not outputting.
 		void set_data_input(uint8_t r);
+
+		/// Gets the value that would appear on the data lines if only the AY is outputting.
 		uint8_t get_data_output();
+
+		/// Sets the
 		void set_control_lines(ControlLines control_lines);
 
+		/*!
+			Gets the value that would appear on the requested interface port if it were in output mode.
+			@parameter port_b @c true to get the value for Port B, @c false to get the value for Port A.
+		*/
 		uint8_t get_port_output(bool port_b);
 
+		// to satisfy ::Outputs::Speaker (included via ::Outputs::Filter; not for public consumption
+		void get_samples(unsigned int number_of_samples, int16_t *target);
+		void skip_samples(unsigned int number_of_samples);
+
 	private:
 		int _selected_register;
 		uint8_t _registers[16], _output_registers[16];