From b1e364f280dc4a1791997c0c43f3013dcdda14ca Mon Sep 17 00:00:00 2001
From: Andrew Belt <andrewpbelt@gmail.com>
Date: Fri, 19 Nov 2021 05:16:34 -0500
Subject: [PATCH] Clean up engine doc comments.

---
 include/engine/Light.hpp     | 11 ++++++-----
 include/engine/LightInfo.hpp |  4 ++--
 include/engine/Port.hpp      |  7 +++++--
 3 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/include/engine/Light.hpp b/include/engine/Light.hpp
index 21f64a9a..d47bdbc9 100644
--- a/include/engine/Light.hpp
+++ b/include/engine/Light.hpp
@@ -21,11 +21,12 @@ struct Light {
 		return value;
 	}
 
-	/** Emulates light decay with slow fall but immediate rise. */
-	void setBrightnessSmooth(float brightness, float deltaTime) {
+	/** Emulates light decay with slow fall but immediate rise.
+	Default lambda set to roughly 2 screen frames.
+	*/
+	void setBrightnessSmooth(float brightness, float deltaTime, float lambda = 30.f) {
 		if (brightness < value) {
 			// Fade out light
-			const float lambda = 30.f;
 			value += (brightness - value) * lambda * deltaTime;
 		}
 		else {
@@ -33,14 +34,14 @@ struct Light {
 			value = brightness;
 		}
 	}
-	/** Alias for setBrightnessSmooth() */
+	/** DEPRECATED Alias for setBrightnessSmooth() */
 	void setSmoothBrightness(float brightness, float deltaTime) {
 		setBrightnessSmooth(brightness, deltaTime);
 	}
 
 	/** Use `setBrightnessSmooth(brightness, sampleTime * frames)` instead. */
 	DEPRECATED void setBrightnessSmooth(float brightness, int frames = 1) {
-		setSmoothBrightness(brightness, frames / 44100.f);
+		setBrightnessSmooth(brightness, frames / 44100.f);
 	}
 };
 
diff --git a/include/engine/LightInfo.hpp b/include/engine/LightInfo.hpp
index 0aa122e6..3f4ed061 100644
--- a/include/engine/LightInfo.hpp
+++ b/include/engine/LightInfo.hpp
@@ -14,10 +14,10 @@ struct LightInfo {
 	int lightId = -1;
 
 	/** The name of the light, using sentence capitalization.
-	e.g. "Level", "Pitch light", "Mode CV".
+	e.g. "Level", "Oscillator phase", "Mode CV".
 
 	Don't use the word "light" or "LED" in the name.
-	Since this text is often prepended or appended to the name, the name will appear as e.g. "Level light light", "Light: Level light".
+	Since this text is often prepended or appended to the name, the name will appear as e.g. "Level light light".
 	*/
 	std::string name;
 
diff --git a/include/engine/Port.hpp b/include/engine/Port.hpp
index 5a2ea0f7..ac92e42f 100644
--- a/include/engine/Port.hpp
+++ b/include/engine/Port.hpp
@@ -20,9 +20,10 @@ struct Port {
 		float value;
 	};
 	union {
-		/** Number of polyphonic channels
+		/** Number of polyphonic channels.
 		DEPRECATED. Unstable API. Use set/getChannels() instead.
 		May be 0 to PORT_MAX_CHANNELS.
+		0 channels means disconnected.
 		*/
 		uint8_t channels = 0;
 		/** DEPRECATED. Unstable API. Use isConnected() instead. */
@@ -103,7 +104,9 @@ struct Port {
 		return sum;
 	}
 
-	/** Returns the root-mean-square of all voltages. */
+	/** Returns the root-mean-square of all voltages.
+	Uses sqrt() which is slow, so use a custom approximation if calling frequently.
+	*/
 	float getVoltageRMS() {
 		if (channels == 0) {
 			return 0.f;