diff --git a/include/Quantity.hpp b/include/Quantity.hpp index a10acca6..c64624af 100644 --- a/include/Quantity.hpp +++ b/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; } diff --git a/include/Window.hpp b/include/Window.hpp index 623fa5b9..e719d923 100644 --- a/include/Window.hpp +++ b/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(); diff --git a/include/asset.hpp b/include/asset.hpp index f7cb1a22..d9874881 100644 --- a/include/asset.hpp +++ b/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") // "//plugins/MyPlugin/samples/00.wav" */ std::string plugin(plugin::Plugin* plugin, std::string filename = ""); diff --git a/include/color.hpp b/include/color.hpp index 8f570c85..2fd21e75 100644 --- a/include/color.hpp +++ b/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); diff --git a/include/discord.hpp b/include/discord.hpp index 6b74b623..593498a1 100644 --- a/include/discord.hpp +++ b/include/discord.hpp @@ -2,6 +2,9 @@ #include namespace rack { + +/** Updates Discord "now playing" status with its IPC API +*/ namespace discord { diff --git a/include/dsp/digital.hpp b/include/dsp/digital.hpp index 91a93f39..f38b7d90 100644 --- a/include/dsp/digital.hpp +++ b/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; diff --git a/include/helpers.hpp b/include/helpers.hpp index 1e897b4b..f084ef56 100644 --- a/include/helpers.hpp +++ b/include/helpers.hpp @@ -19,8 +19,9 @@ namespace rack { +/** Returns a Model that constructs a Module and ModuleWidget subclass. */ template -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 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 TWidget* createWidgetCentered(math::Vec pos) { TWidget* o = createWidget(pos); diff --git a/include/network.hpp b/include/network.hpp index 73a45e22..1d613f1f 100644 --- a/include/network.hpp +++ b/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); diff --git a/include/plugin.hpp b/include/plugin.hpp index 2a826093..34fb71b2 100644 --- a/include/plugin.hpp +++ b/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. diff --git a/include/plugin/callbacks.hpp b/include/plugin/callbacks.hpp index 7a72faa0..bb82d20a 100644 --- a/include/plugin/callbacks.hpp +++ b/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); +} diff --git a/include/simd/vector.hpp b/include/simd/vector.hpp index 28690daa..989b65b2 100644 --- a/include/simd/vector.hpp +++ b/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); diff --git a/include/string.hpp b/include/string.hpp index ea05b326..9d347667 100644 --- a/include/string.hpp +++ b/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 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); diff --git a/include/svg.hpp b/include/svg.hpp index 768d44d5..c9a12294 100644 --- a/include/svg.hpp +++ b/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(); diff --git a/include/tag.hpp b/include/tag.hpp index ba8effd4..4431dc4f 100644 --- a/include/tag.hpp +++ b/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); diff --git a/include/ui/PasswordField.hpp b/include/ui/PasswordField.hpp index e3d81000..b8c0b723 100644 --- a/include/ui/PasswordField.hpp +++ b/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; };