Add/edit doc comments.

include/Quantity.hpp

@@ -25,12 +25,12 @@ struct Quantity {
 		return 0.f;
 	}
 
-	/** Returns the minimum allowed value. */
+	/** Returns the minimum recommended value. */
 	virtual float getMinValue() {
 		return 0.f;
 	}
 
-	/** Returns the maximum allowed value. */
+	/** Returns the maximum recommended value. */
 	virtual float getMaxValue() {
 		return 1.f;
 	}

include/Window.hpp

@@ -71,6 +71,7 @@ struct Window {
 	Skips screenshot if the file already exists.
 	*/
 	void screenshotModules(const std::string& screenshotsDir, float zoom = 1.f);
+	/** Request Window to be closed after rendering the current frame. */
 	void close();
 	void cursorLock();
 	void cursorUnlock();

include/asset.hpp

@@ -20,16 +20,17 @@ namespace asset {
 
 void init();
 
-/** Returns the path of a system asset. Should only read files from this location. */
+/** Returns the path of a system asset. Read-only files. */
 std::string system(std::string filename = "");
 
-/** Returns the path of a user asset. Can read and write files to this location. */
+/** Returns the path of a user asset. Readable/writable files. */
 std::string user(std::string filename = "");
 
-/** Returns the path of a asset in the plugin's dir.
-Plugin assets should be read-only by plugins.
+/** Returns the path of an asset in the plugin's dir. Read-only files.
+
 Examples:
-	asset::plugin(pluginInstance, "samples/00.wav") // "/path/to/Rack/user/dir/plugins/MyPlugin/samples/00.wav"
+
+	asset::plugin(pluginInstance, "samples/00.wav") // "/<Rack user dir>/plugins/MyPlugin/samples/00.wav"
 */
 std::string plugin(plugin::Plugin* plugin, std::string filename = "");
 

include/color.hpp

@@ -27,14 +27,22 @@ static const NVGcolor WHITE = nvgRGB(0xff, 0xff, 0xff);
 
 
 bool isEqual(NVGcolor a, NVGcolor b);
+/** Limits color components between 0 and 1. */
 NVGcolor clamp(NVGcolor a);
+/** Subtracts color components elementwise. */
 NVGcolor minus(NVGcolor a, NVGcolor b);
+/** Adds color components elementwise. */
 NVGcolor plus(NVGcolor a, NVGcolor b);
+/** Multiplies color components elementwise. */
 NVGcolor mult(NVGcolor a, NVGcolor b);
 NVGcolor mult(NVGcolor a, float x);
 /** Screen blending with alpha compositing */
 NVGcolor screen(NVGcolor a, NVGcolor b);
+/** Multiplies alpha value. */
 NVGcolor alpha(NVGcolor a, float alpha);
+/** Converts from color hex string of the form "#RRGGBB" or "#RRGGBBAA".
+Returns WHITE on error.
+*/
 NVGcolor fromHexString(std::string s);
 std::string toHexString(NVGcolor c);
 

include/discord.hpp

@@ -2,6 +2,9 @@
 #include <common.hpp>
 
 namespace rack {
+
+/** Updates Discord "now playing" status with its IPC API
+*/
 namespace discord {
 
 

include/dsp/digital.hpp

@@ -111,6 +111,7 @@ struct PulseGenerator {
 };
 
 
+/** Accumulates a timer when process() is called. */
 struct Timer {
 	float time = 0.f;
 
@@ -126,6 +127,13 @@ struct Timer {
 };
 
 
+/** Counts calls to process(), returning true every `division` calls.
+Example:
+
+	if (divider.process()) {
+		// Runs every `division` calls
+	}
+*/
 struct ClockDivider {
 	uint32_t clock = 0;
 	uint32_t division = 1;

include/helpers.hpp

@@ -19,8 +19,9 @@
 namespace rack {
 
 
+/** Returns a Model that constructs a Module and ModuleWidget subclass. */
 template <class TModule, class TModuleWidget>
-plugin::Model* createModel(const std::string& slug) {
+plugin::Model* createModel(std::string slug) {
 	struct TModel : plugin::Model {
 		engine::Module* createModule() override {
 			engine::Module* m = new TModule;
@@ -45,6 +46,7 @@ plugin::Model* createModel(const std::string& slug) {
 }
 
 
+/** Creates a Widget subclass with its top-left at a position. */
 template <class TWidget>
 TWidget* createWidget(math::Vec pos) {
 	TWidget* o = new TWidget;
@@ -53,6 +55,7 @@ TWidget* createWidget(math::Vec pos) {
 }
 
 
+/** Creates a Widget subclass with its center at a position. */
 template <class TWidget>
 TWidget* createWidgetCentered(math::Vec pos) {
 	TWidget* o = createWidget<TWidget>(pos);

include/network.hpp

@@ -28,11 +28,17 @@ void init();
 Caller must json_decref() if return value is non-NULL.
 */
 json_t* requestJson(Method method, const std::string& url, json_t* dataJ = NULL, const CookieMap& cookies = {});
-/** Returns true if downloaded successfully */
+/** Returns true if downloaded successfully.
+If `progress` is non-NULL, the value is updated from 0 to 1 while downloading.
+*/
 bool requestDownload(const std::string& url, const std::string& filename, float* progress, const CookieMap& cookies = {});
-/** URL-encodes `s` */
+/** URL-encodes a string. */
 std::string encodeUrl(const std::string& s);
-/** Gets the path portion of the URL. */
+/** Returns the path portion of the URL.
+Example:
+
+	urlPath("https://example.com/foo/index.html") // Returns "/foo/index.html"
+*/
 std::string urlPath(const std::string& url);
 
 

include/plugin.hpp

@@ -16,7 +16,9 @@ namespace plugin {
 
 void init();
 void destroy();
+/** Finds a loaded Plugin by slug. */
 Plugin* getPlugin(const std::string& pluginSlug);
+/** Finds a loaded Model by plugin and model slug. */
 Model* getModel(const std::string& pluginSlug, const std::string& modelSlug);
 /** Creates a Model from a JSON module object.
 Throws an Exception if the model is not found.

include/plugin/callbacks.hpp

@@ -5,5 +5,6 @@
 /** Called once to initialize and return the Plugin instance.
 You must implement this in your plugin
 */
-extern "C"
+extern "C" {
 void init(rack::plugin::Plugin* plugin);
+}

include/simd/vector.hpp

@@ -14,7 +14,7 @@ namespace simd {
 
 This class is designed to be used just like you use scalars, with extra features for handling bitwise logic, conditions, loading, and storing.
 
-Usage example:
+Example:
 
 	float a[4], b[4];
 	float_4 a = float_4::load(in);

include/string.hpp

@@ -14,7 +14,7 @@ namespace string {
 
 
 /** Converts a `printf()` format string and optional arguments into a std::string.
-Remember that "%s" must reference a `char *`, so use `.c_str()` for `std::string`s, otherwise you might get binary garbage.
+Remember that "%s" must reference a `char *`, so use `.c_str()` for `std::string`s, otherwise you will get binary garbage.
 */
 __attribute__((format(printf, 1, 2)))
 std::string f(const char* format, ...);
@@ -25,10 +25,13 @@ std::string lowercase(const std::string& s);
 std::string uppercase(const std::string& s);
 /** Removes whitespace from beginning and end of string. */
 std::string trim(const std::string& s);
-/** Truncates and adds "..." to a string, not exceeding `len` characters */
+/** Truncates and adds "..." to the end of a string, not exceeding `len` characters. */
 std::string ellipsize(const std::string& s, size_t len);
+/** Truncates and adds "..." to the beginning of a string, not exceeding `len` characters. */
 std::string ellipsizePrefix(const std::string& s, size_t len);
+/** Returns whether a string starts with the given substring. */
 bool startsWith(const std::string& str, const std::string& prefix);
+/** Returns whether a string ends with the given substring. */
 bool endsWith(const std::string& str, const std::string& suffix);
 
 /** Scores how well a query matches a string.
@@ -79,6 +82,7 @@ Examples:
 */
 std::vector<std::string> split(const std::string& s, const std::string& seperator, size_t maxTokens = 0);
 
+/** Formats a UNIX timestamp with a strftime() string. */
 std::string formatTime(const char* format, double timestamp);
 std::string formatTimeISO(double timestamp);
 

include/svg.hpp

@@ -43,6 +43,7 @@ struct Svg {
 	void loadFile(const std::string& filename);
 	/** Loads SVG data from a string. */
 	void loadString(const std::string& str);
+	/** Returns the SVG page size in pixels. */
 	math::Vec getSize();
 	int getNumShapes();
 	int getNumPaths();

include/tag.hpp

@@ -24,6 +24,7 @@ Returns -1 if not found.
 */
 int findId(const std::string& tag);
 
+/** Returns the main tag name by tag ID. */
 std::string getTag(int tagId);
 
 

include/ui/PasswordField.hpp

@@ -7,6 +7,7 @@ namespace rack {
 namespace ui {
 
 
+/** A TextField that hides/replaces all characters with "*" */
 struct PasswordField : TextField {
 	void draw(const DrawArgs& args) override;
 };