From 97c03ea4646af612a22027269b7acb2983f1598a Mon Sep 17 00:00:00 2001
From: Andrew Belt <andrewpbelt@gmail.com>
Date: Fri, 20 Mar 2020 21:34:52 -0400
Subject: [PATCH] Improve documentation for Module.

---
 docs/Makefile                    |  2 +-
 include/engine/Module.hpp        | 15 ++++++++++++++-
 include/engine/ParamQuantity.hpp | 10 +++++++++-
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 0d4a9321..fc111d9f 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -8,7 +8,7 @@ run: doxygen
 	http-server html
 
 upload: doxygen
-	rsync html/ vcvrack.com:vcvrack.com/docs/ -ruz --info=progress2 --delete
+	rsync html/ vcvrack.com:vcvrack.com/docs-v2/ -ruz --info=progress2 --delete
 
 clean:
 	rm -rfv html
diff --git a/include/engine/Module.hpp b/include/engine/Module.hpp
index 724b901d..dd3b5cce 100644
--- a/include/engine/Module.hpp
+++ b/include/engine/Module.hpp
@@ -97,6 +97,9 @@ struct Module {
 	/** Configures the number of Params, Outputs, Inputs, and Lights. */
 	void config(int numParams, int numInputs, int numOutputs, int numLights = 0);
 
+	/** Helper for creating a ParamQuantity and setting its properties.
+	See ParamQuantity for documentation of arguments.
+	*/
 	template <class TParamQuantity = ParamQuantity>
 	TParamQuantity* configParam(int paramId, float minValue, float maxValue, float defaultValue, std::string name = "", std::string unit = "", float displayBase = 0.f, float displayMultiplier = 1.f, float displayOffset = 0.f) {
 		assert(paramId < (int) params.size() && paramId < (int) paramQuantities.size());
@@ -121,6 +124,9 @@ struct Module {
 		return q;
 	}
 
+	/** Helper for creating a SwitchQuantity and setting its label strings.
+	See ParamQuantity and SwitchQuantity for documentation of arguments.
+	*/
 	template <class TSwitchQuantity = SwitchQuantity>
 	TSwitchQuantity* configSwitch(int paramId, float minValue, float maxValue, float defaultValue, std::string name = "", std::vector<std::string> labels = {}) {
 		TSwitchQuantity* sq = configParam<TSwitchQuantity>(paramId, minValue, maxValue, defaultValue, name);
@@ -128,6 +134,9 @@ struct Module {
 		return sq;
 	}
 
+	/** Helper for creating a PortInfo for an input port and setting its properties.
+	See PortInfo for documentation of arguments.
+	*/
 	template <class TPortInfo = PortInfo>
 	TPortInfo* configInput(int portId, std::string name = "") {
 		assert(portId < (int) inputs.size() && portId < (int) inputInfos.size());
@@ -143,6 +152,9 @@ struct Module {
 		return p;
 	}
 
+	/** Helper for creating a PortInfo for an output port and setting its properties.
+	See PortInfo for documentation of arguments.
+	*/
 	template <class TPortInfo = PortInfo>
 	TPortInfo* configOutput(int portId, std::string name = "") {
 		assert(portId < (int) outputs.size() && portId < (int) outputInfos.size());
@@ -158,7 +170,8 @@ struct Module {
 		return p;
 	}
 
-	/** Adds a direct route from an input to an output when the module is bypassed. */
+	/** Adds a direct route from an input to an output when the module is bypassed.
+	*/
 	void configBypass(int inputId, int outputId) {
 		assert(inputId < (int) inputs.size());
 		assert(outputId < (int) outputs.size());
diff --git a/include/engine/ParamQuantity.hpp b/include/engine/ParamQuantity.hpp
index 284f811d..1a2dcffe 100644
--- a/include/engine/ParamQuantity.hpp
+++ b/include/engine/ParamQuantity.hpp
@@ -33,10 +33,18 @@ struct ParamQuantity : Quantity {
 	Unit symbols should have no space (e.g. "%", "º").
 	*/
 	std::string unit;
-	/** Set to 0 for linear, positive for exponential, negative for logarithmic. */
+	/** Set to 0 for linear, positive for exponential, negative for logarithmic.
+	The formula is $displayValue = f(value) * displayMultiplier + displayOffset$ where $f(value)$ is
+	- $value$ for $displayBase = 0$.
+	- $log_{-displayBase}(value)$ for $displayBase < 0$.
+	- $displayBase^value$ for $displayBase > 0$.
+	*/
 	float displayBase = 0.f;
 	float displayMultiplier = 1.f;
 	float displayOffset = 0.f;
+	/** Number of digits of precision to display.
+	With displayPrecision = 5 for example, numbers will print as 12.345, 0.12345, 1.2345e6, or 1.2345e-6.
+	*/
 	int displayPrecision = 5;
 	/** An optional one-sentence description of the parameter. */
 	std::string description;