From 42fa5e8d4de1242cf5fd1ad3f1fd97639ce673d5 Mon Sep 17 00:00:00 2001
From: DarkWiiPlayer <darkwiiplayer@hotmail.com>
Date: Sat, 2 Jul 2022 10:55:38 +0200
Subject: [PATCH] Document speaker class

---
 index.html        | 18 ++++++++++
 page/speaker.html | 88 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)
 create mode 100644 page/speaker.html

diff --git a/index.html b/index.html
index 97071a8..e75451a 100644
--- a/index.html
+++ b/index.html
@@ -15,6 +15,8 @@
 	<p style="text-align: center;">
 		A collection of <em>JavaScript modules</em> to make <em>front-end</em> easier.
 	</p>
+	<p>
+	</p>
 </section>
 
 <section>
@@ -81,6 +83,22 @@
 	</p>
 </section>
 
+<section>
+	<h2>Speaker</h2>
+	<p>
+		Publish and subscribe to messages, relayed via micro-tasks.
+		<a class="fancy" href="page/speaker.html">Read More</a>
+
+		<code-block>
+			const speaker = new Speaker()
+			speaker.listen((...args) =&gt; console.log(...args))
+			speaker.speak("First", "second", "third")
+		</code-block>
+
+		No, this has nothing to do with playing audio.
+	</p>
+</section>
+
 <section>
 	<h2>Debounce</h2>
 	<p>
diff --git a/page/speaker.html b/page/speaker.html
new file mode 100644
index 0000000..254e93b
--- /dev/null
+++ b/page/speaker.html
@@ -0,0 +1,88 @@
+
+<link rel="stylesheet" href="style.css">
+
+<script type="module" src="codeblock.js"></script>
+<script type="module" src="scrollToTop.js"></script>
+
+<scroll-to-top>
+</scroll-to-top>
+
+<a class="back" href="..">Module Index</a>
+
+<h1 class="js module">speaker.js</h1>
+
+<code-block>import {Speaker} from 'speaker.js'</code-block>
+
+<section>
+	<h2>Description</h2>
+	<p>
+		A publish/subscribe helper class that uses micro-tasks to relay messages to many subscribers.
+	</p>
+</section>
+
+<section>
+	<h2>Example</h2>
+
+	<code-block>
+		const speaker = new Speaker()
+		speaker.listen(message =&gt; { document.title = message })
+		speaker.listen(message =&gt; { console.log(`Message received: ${message}`) })
+
+		speaker.speak("New page title")
+		console.log("This line runs before any of the callbacks")
+	</code-block>
+
+	<p>
+		Note that the callbacks don't run immediately.
+		They are scheduled to a micro-task to be called later on.
+	</p>
+
+</section>
+
+<section>
+	<h2>Methods</h2>
+	<dl>
+		<dt><code>new Speaker(...initial) : Speaker</code></dt>
+		<dd>
+			Constructs a new speaker.
+			All arguments passed to the constructor will be retained and returned
+			by any call to <code>listen</code> before the first time <code>speak</code>
+			is called.
+		</dd>
+
+		<dt><code>Speaker.listen(callback : (...args) =&gt; undefined) : [...args]</code></dt>
+		<dd>
+			Registers a callback to be called on every new message.
+			Returns an array containing the retained arguments of the last message.
+		</dd>
+
+		<dt><code>Speaker.speak(...args)</code></dt>
+		<dd>
+			Relays a message of zero or more arguments to all registered callbacks.
+			As mentioned above, callbacks will not be called immediately, but scheduled in a new micro-task.
+			The arguments are retained until <code>speak</code> is called again.
+		</dd>
+
+		<dt><code>Speaker.forget(callback)</code></dt>
+		<dd>
+			Removes a single callback function from its list of callbacks.
+		</dd>
+
+		<dt><code>Speaker.silence()</code></dt>
+		<dd>
+			Clears the list of callbacks completely.
+		</dd>
+	</dl>
+</section>
+
+<section>
+	<h2>Immediate Speaker</h2>
+	<p>
+		Additionally, the module exposts the <code>ImmediateSpeaker</code> class,
+		which does the exact same as a normal speaker,
+		but executes its callbacks immediately instead of scheduling a micro-task.
+	</p>
+	<p>
+		The API is the <em>exact same</em> as a normal <code>Speaker</code>.
+	</p>
+</section>