Clean up engine doc comments.

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);
 	}
 };
 

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;
 

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;