Add more engine docstrings

include/dsp/resampler.hpp

@@ -12,6 +12,7 @@ namespace rack {
 namespace dsp {
 
 
+/** Resamples by a fixed rational factor. */
 template<int CHANNELS>
 struct SampleRateConverter {
 	SpeexResamplerState *st = NULL;
@@ -101,6 +102,7 @@ struct SampleRateConverter {
 };
 
 
+/** Downsamples by an integer factor. */
 template<int OVERSAMPLE, int QUALITY>
 struct Decimator {
 	float inBuffer[OVERSAMPLE*QUALITY];
@@ -135,6 +137,7 @@ struct Decimator {
 };
 
 
+/** Upsamples by an integer factor. */
 template<int OVERSAMPLE, int QUALITY>
 struct Upsampler {
 	float inBuffer[QUALITY];

include/engine/Engine.hpp

@@ -15,21 +15,21 @@ struct Engine {
 
 	Engine();
 	~Engine();
-	/** Starts engine thread */
+	/** Starts engine thread. */
 	void start();
-	/** Stops engine thread */
+	/** Stops engine thread. */
 	void stop();
 	void setThreadCount(int threadCount);
 	int getThreadCount();
 	void setPaused(bool paused);
 	bool isPaused();
-	/** Does not transfer pointer ownership */
+	/** Does not transfer pointer ownership. */
 	void addModule(Module *module);
 	void removeModule(Module *module);
 	void resetModule(Module *module);
 	void randomizeModule(Module *module);
 	void bypassModule(Module *module, bool bypass);
-	/** Does not transfer pointer ownership */
+	/** Does not transfer pointer ownership. */
 	void addCable(Cable *cable);
 	void removeCable(Cable *cable);
 	void setParam(Module *module, int paramId, float value);

include/engine/Light.hpp

@@ -7,11 +7,12 @@ namespace engine {
 
 
 struct Light {
-	/** The mean-square of the brightness
+	/** The mean-square of the brightness.
 	Unstable API. Use set/getBrightness().
 	*/
 	float value = 0.f;
 
+	/** Sets the brightness directly with no LED modeling. */
 	void setBrightness(float brightness) {
 		value = (brightness > 0.f) ? std::pow(brightness, 2) : 0.f;
 	}
@@ -21,7 +22,8 @@ struct Light {
 	}
 
 	/** Emulates slow fall (but immediate rise) of LED brightness.
-	`frames` rescales the timestep. For example, if your module calls this method every 16 frames, use 16.f.
+	`frames` rescales the timestep.
+	For example, if your module calls this method every 16 frames, use 16.f.
 	*/
 	void setBrightnessSmooth(float brightness, float frames = 1.f) {
 		float v = (brightness > 0.f) ? std::pow(brightness, 2) : 0.f;

include/engine/Module.hpp

@@ -13,42 +13,44 @@ namespace engine {
 
 
 struct Module {
+	/** Automatically generated by the engine. */
 	int id = 0;
 	std::vector<Param> params;
 	std::vector<Output> outputs;
 	std::vector<Input> inputs;
 	std::vector<Light> lights;
-	/** For power meter */
+	/** For CPU meter. */
 	float cpuTime = 0.f;
 	bool bypass = false;
 
-	/** Constructs a Module with no params, inputs, outputs, and lights */
+	/** Constructs a Module with no params, inputs, outputs, and lights. */
 	Module();
-	/** Deprecated. Use config() instead. */
+	/** Use config() instead. */
 	DEPRECATED Module(int numParams, int numInputs, int numOutputs, int numLights = 0) : Module() {
 		config(numParams, numInputs, numOutputs, numLights);
 	}
 	virtual ~Module() {}
 
+	/** Configures the number of Params, Outputs, Inputs, and Lights. */
 	void config(int numParams, int numInputs, int numOutputs, int numLights = 0);
 	json_t *toJson();
 	void fromJson(json_t *rootJ);
 	void reset();
 	void randomize();
 
-	/** Advances the module by 1 audio frame with duration 1.0 / gSampleRate
-	Override this method to read inputs and params, and to write outputs and lights.
+	/** Advances the module by one audio sample.
+	Override this method to read Inputs and Params, and to write Outputs and Lights.
 	*/
 	virtual void step() {}
 
-	/** Called when the engine sample rate is changed */
+	/** Called when the engine sample rate is changed. */
 	virtual void onSampleRateChange() {}
-	/** Called when user clicks Initialize in the module context menu */
+	/** Called when user clicks Initialize in the module context menu. */
 	virtual void onReset() {}
-	/** Called when user clicks Randomize in the module context menu */
+	/** Called when user clicks Randomize in the module context menu. */
 	virtual void onRandomize() {}
 
-	/** Override these to store extra internal data in the "data" property of the module's JSON object */
+	/** Override to store extra internal data in the "data" property of the module's JSON object. */
 	virtual json_t *dataToJson() { return NULL; }
 	virtual void dataFromJson(json_t *root) {}
 };

include/engine/Param.hpp

@@ -22,30 +22,33 @@ struct ParamQuantityFactory {
 
 
 struct Param {
-	/** Unstable API. Use set/getValue() instead. */
+	/** Unstable API. Use setValue() and getValue() instead. */
 	float value = 0.f;
 
+	/** The minimum allowed value. */
 	float minValue = 0.f;
+	/** The maximum allowed value. Must be greater than minValue. */
 	float maxValue = 1.f;
+	/** The initial value. */
 	float defaultValue = 0.f;
 
-	/** The name of the parameter in sentence capitalization
+	/** The name of the parameter, using sentence capitalization.
 	e.g. "Frequency", "Pulse width", "Alternative mode"
 	*/
 	std::string label;
-	/** The numerical unit of measurement
+	/** The numerical unit of measurement appended to the value.
 	Use a space before non-abbreviations to separate the numerical value.
 	e.g. " semitones", "Hz", "%", "V"
 	*/
 	std::string unit;
-	/** Set to 0 for linear, nonzero for exponential */
+	/** Set to 0 for linear, nonzero for exponential. */
 	float displayBase = 0.f;
 	float displayMultiplier = 1.f;
 	float displayOffset = 0.f;
-	/** An optional one-sentence description of the parameter */
+	/** An optional one-sentence description of the parameter. */
 	std::string description;
 	ParamQuantityFactory *paramQuantityFactory = NULL;
-	/** Determines whether this param will be randomized automatically when the user requests to randomize the module state */
+	/** Determines whether this Param will be randomized when the user requests to randomize the Module. */
 	bool randomizable = true;
 
 	~Param() {
@@ -82,6 +85,7 @@ struct Param {
 		this->value = math::clamp(value, minValue, maxValue);
 	}
 
+	/** Returns whether the Param has finite range between minValue and maxValue. */
 	bool isBounded();
 	json_t *toJson();
 	void fromJson(json_t *rootJ);

include/engine/Port.hpp

@@ -13,7 +13,7 @@ static const int PORT_MAX_CHANNELS = 16;
 struct Port {
 	/** Voltage of the port. */
 	union {
-		/** Unstable API. Use set/getVoltage() instead. */
+		/** Unstable API. Use getVoltage() and setVoltage() instead. */
 		float voltages[PORT_MAX_CHANNELS] = {};
 		/** DEPRECATED. Unstable API. Use getVoltage() and setVoltage() instead. */
 		float value;
@@ -26,7 +26,7 @@ struct Port {
 	/** Unstable API. Use isConnected() instead. */
 	bool active;
 	/** For rendering plug lights on cables.
-	Green for positive, red for negative, and blue for polyphonic
+	Green for positive, red for negative, and blue for polyphonic.
 	*/
 	Light plugLights[3];
 
@@ -55,6 +55,7 @@ struct Port {
 		return isConnected() ? getPolyVoltage(channel) : normalVoltage;
 	}
 
+	/** Sets the number of polyphony channels. */
 	void setChannels(int channels) {
 		// Set higher channel voltages to 0
 		for (int c = channels; c < this->channels; c++) {
@@ -67,12 +68,16 @@ struct Port {
 		return channels;
 	}
 
+	/** Returns if a cable is connected to the Port.
+	You can use this for skipping code that generates output voltages.
+	*/
 	bool isConnected() {
 		return active;
 	}
 
 	void step();
 
+	/** Use getNormalVoltage() instead. */
 	DEPRECATED float normalize(float normalVoltage) {
 		return getNormalVoltage(normalVoltage);
 	}