From d5b86f458b405dab77f9dd7bde0fefdd03127b60 Mon Sep 17 00:00:00 2001
From: Andrew Belt <andrewpbelt@gmail.com>
Date: Thu, 23 Sep 2021 06:29:39 -0400
Subject: [PATCH] Add doc comments to dsp and engine namespaces.

---
 include/app/ParamWidget.hpp      | 5 +++++
 include/dsp/filter.hpp           | 7 +++++++
 include/dsp/vumeter.hpp          | 1 -
 include/engine/Module.hpp        | 8 ++++++++
 include/engine/ParamQuantity.hpp | 2 +-
 include/engine/Port.hpp          | 2 +-
 include/plugin/Model.hpp         | 3 +++
 7 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/include/app/ParamWidget.hpp b/include/app/ParamWidget.hpp
index 5042c8b8..bfca2ee9 100644
--- a/include/app/ParamWidget.hpp
+++ b/include/app/ParamWidget.hpp
@@ -37,6 +37,11 @@ struct ParamWidget : widget::OpaqueWidget {
 	void onLeave(const LeaveEvent& e) override;
 
 	void createContextMenu();
+	/** Override to add custom menu items at the bottom of the parameter context menu.
+	It is recommended to add a MenuSeparator before other menu items.
+
+		menu->addChild(new MenuSeparator);
+	*/
 	virtual void appendContextMenu(ui::Menu* menu) {}
 	void resetAction();
 };
diff --git a/include/dsp/filter.hpp b/include/dsp/filter.hpp
index 6d93ec85..8f01836b 100644
--- a/include/dsp/filter.hpp
+++ b/include/dsp/filter.hpp
@@ -68,6 +68,7 @@ struct TExponentialFilter {
 		this->lambda = lambda;
 	}
 
+	/** Sets \f$ \lambda = 1 / \tau \f$. */
 	void setTau(T tau) {
 		this->lambda = 1 / tau;
 	}
@@ -127,6 +128,7 @@ struct TPeakFilter {
 typedef TPeakFilter<> PeakFilter;
 
 
+/** Limits the derivative of the output by a rise and fall speed, in units/s. */
 template <typename T = float>
 struct TSlewLimiter {
 	T out = 0.f;
@@ -153,6 +155,7 @@ struct TSlewLimiter {
 typedef TSlewLimiter<> SlewLimiter;
 
 
+/** Behaves like ExponentialFilter but with different lambas when the RHS of the ODE is positive or negative. */
 template <typename T = float>
 struct TExponentialSlewLimiter {
 	T out = 0.f;
@@ -167,6 +170,10 @@ struct TExponentialSlewLimiter {
 		this->riseLambda = riseLambda;
 		this->fallLambda = fallLambda;
 	}
+	void setRiseFallTau(T riseTau, T fallTau) {
+		this->riseLambda = 1 / riseTau;
+		this->fallLambda = 1 / fallTau;
+	}
 	T process(T deltaTime, T in) {
 		T lambda = simd::ifelse(in > out, riseLambda, fallLambda);
 		T y = out + (in - out) * lambda * deltaTime;
diff --git a/include/dsp/vumeter.hpp b/include/dsp/vumeter.hpp
index 0b53e07b..ffe165fa 100644
--- a/include/dsp/vumeter.hpp
+++ b/include/dsp/vumeter.hpp
@@ -29,7 +29,6 @@ struct VuMeter {
 	}
 };
 
-
 DEPRECATED typedef VuMeter VUMeter;
 
 
diff --git a/include/engine/Module.hpp b/include/engine/Module.hpp
index 6511b721..f8ab792c 100644
--- a/include/engine/Module.hpp
+++ b/include/engine/Module.hpp
@@ -83,6 +83,10 @@ struct Module {
 		void* producerMessage = NULL;
 		void* consumerMessage = NULL;
 		bool messageFlipRequested = false;
+
+		void requestMessageFlip() {
+			messageFlipRequested = true;
+		}
 	};
 
 	Expander leftExpander;
@@ -280,6 +284,7 @@ struct Module {
 	Expander& getRightExpander() {
 		return rightExpander;
 	}
+	/** Returns the left Expander if `side` is false, andright Expander if `side` is true. */ 
 	Expander& getExpander(bool side) {
 		return side ? rightExpander : leftExpander;
 	}
@@ -327,6 +332,9 @@ struct Module {
 	virtual json_t* dataToJson() {
 		return NULL;
 	}
+	/** Override to load internal data from the "data" property of the module's JSON object.
+	Not called if "data" property is not present.
+	*/
 	virtual void dataFromJson(json_t* rootJ) {}
 
 	///////////////////////
diff --git a/include/engine/ParamQuantity.hpp b/include/engine/ParamQuantity.hpp
index 8608af8e..6f4edba0 100644
--- a/include/engine/ParamQuantity.hpp
+++ b/include/engine/ParamQuantity.hpp
@@ -64,7 +64,7 @@ struct ParamQuantity : Quantity {
 	bool snapEnabled = false;
 
 	Param* getParam();
-	/** If smoothEnabled is true, requests to the engine to smoothly set the value. */
+	/** If smoothEnabled is true, requests to the engine to smoothly move to a target value each sample. */
 	void setSmoothValue(float value);
 	float getSmoothValue();
 
diff --git a/include/engine/Port.hpp b/include/engine/Port.hpp
index cb5ddc69..5a2ea0f7 100644
--- a/include/engine/Port.hpp
+++ b/include/engine/Port.hpp
@@ -21,7 +21,7 @@ struct Port {
 	};
 	union {
 		/** Number of polyphonic channels
-		Unstable API. Use set/getChannels() instead.
+		DEPRECATED. Unstable API. Use set/getChannels() instead.
 		May be 0 to PORT_MAX_CHANNELS.
 		*/
 		uint8_t channels = 0;
diff --git a/include/plugin/Model.hpp b/include/plugin/Model.hpp
index a518eef0..8e8b0df5 100644
--- a/include/plugin/Model.hpp
+++ b/include/plugin/Model.hpp
@@ -28,6 +28,9 @@ struct Module;
 namespace plugin {
 
 
+/** Type information for a module.
+Factory for Module and ModuleWidget.
+*/
 struct Model {
 	Plugin* plugin = NULL;