Add various API documentation

docs/Makefile

@@ -4,6 +4,9 @@ all: doxygen
 doxygen:
 	doxygen Doxyfile
 
+run: doxygen
+	http-server html
+
 upload: doxygen
 	rsync html/ vcvrack.com:vcvrack.com/docs/ -ruvz --delete
 

include/app.hpp

@@ -28,6 +28,8 @@ struct Window;
 struct PatchManager;
 
 
+/** Rack-specific GUI widgets and functions that control and offer feedback for the rack state.
+*/
 namespace app {
 
 

include/app/ModuleWidget.hpp

@@ -12,6 +12,7 @@ namespace rack {
 namespace app {
 
 
+/** Manages an engine::Module in the rack. */
 struct ModuleWidget : widget::OpaqueWidget {
 	plugin::Model *model = NULL;
 	/** Owns the module pointer */

include/app/ParamQuantity.hpp

@@ -8,7 +8,7 @@ namespace rack {
 namespace app {
 
 
-/** A ui::Quantity that wraps an engine Param */
+/** A ui::Quantity that wraps an engine::Param. */
 struct ParamQuantity : ui::Quantity {
 	engine::Module *module = NULL;
 	int paramId = 0;

include/app/ParamWidget.hpp

@@ -10,6 +10,7 @@ namespace rack {
 namespace app {
 
 
+/** Manages an engine::Param on a ModuleWidget. */
 struct ParamWidget : widget::OpaqueWidget {
 	ParamQuantity *paramQuantity = NULL;
 	float dirtyValue = NAN;

include/app/PortWidget.hpp

@@ -9,6 +9,7 @@ namespace rack {
 namespace app {
 
 
+/** Manages an engine::Port on a ModuleWidget. */
 struct PortWidget : widget::OpaqueWidget {
 	engine::Module *module = NULL;
 	int portId;

include/app/RackWidget.hpp

@@ -12,6 +12,7 @@ namespace rack {
 namespace app {
 
 
+/** Container for ModuleWidget and CableWidget. */
 struct RackWidget : widget::OpaqueWidget {
 	widget::FramebufferWidget *rails;
 	widget::Widget *moduleContainer;

include/audio.hpp

@@ -11,6 +11,10 @@
 
 
 namespace rack {
+
+
+/** Audio driver
+*/
 namespace audio {
 
 

include/color.hpp

@@ -5,6 +5,9 @@
 
 
 namespace rack {
+
+/** Utilities for `NVGcolor`
+*/
 namespace color {
 
 

include/component.hpp

@@ -3,6 +3,16 @@
 
 
 namespace rack {
+
+/** Component Library by [Grayscale](https://grayscale.info/).
+
+Copied from `LICENSE.md`:
+
+The **Component Library graphics** in the `res/ComponentLibrary` directory are copyright © 2019 [Grayscale](http://grayscale.info/) and licensed under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/).
+You may not freely sell plugins using Component Library graphics.
+However, a free commercial license is available for plugins sold through the [VCV Store](https://vcvrack.com/plugins.html).
+Email contact@vcvrack.com for more information about licensing or the VCV Store.
+*/
 namespace component {
 
 

include/dsp/common.hpp

@@ -3,6 +3,10 @@
 
 
 namespace rack {
+
+
+/** Digital signal processing routines for plugins
+*/
 namespace dsp {
 
 

include/engine/Module.hpp

@@ -39,7 +39,7 @@ struct Module {
 	void randomize();
 
 	/** Advances the module by one audio sample.
-	Override this method to read Inputs and Params, and to write Outputs and Lights.
+	Override this method to read Inputs and Params and to write Outputs and Lights.
 	*/
 	virtual void step() {}
 

include/event.hpp

@@ -12,6 +12,8 @@ namespace widget {
 } // namespace widget
 
 
+/** Event state machine for Widgets
+*/
 namespace event {
 
 

include/gamepad.hpp

@@ -3,6 +3,10 @@
 
 
 namespace rack {
+
+
+/** Gamepad/joystick/controller MIDI driver
+*/
 namespace gamepad {
 
 

include/history.hpp

@@ -16,6 +16,7 @@ namespace app {
 } // namespace app
 
 
+/** Undo history actions for the Rack application */
 namespace history {
 
 

include/keyboard.hpp

@@ -3,6 +3,10 @@
 
 
 namespace rack {
+
+
+/** Computer keyboard MIDI driver
+*/
 namespace keyboard {
 
 

include/logger.hpp

@@ -13,6 +13,10 @@ will print something like
 
 
 namespace rack {
+
+
+/** Logs messages to a file or the console with decoration
+*/
 namespace logger {
 
 
@@ -25,7 +29,9 @@ enum Level {
 
 void init(bool devMode);
 void destroy();
-/** Do not use this function directly. Use the macros below. */
+/** Do not use this function directly. Use the macros below.
+Thread-safe.
+*/
 void log(Level level, const char *filename, int line, const char *format, ...);
 
 

include/math.hpp

@@ -4,6 +4,10 @@
 
 
 namespace rack {
+
+
+/** Supplemental `<cmath>` functions and types
+*/
 namespace math {
 
 

include/midi.hpp

@@ -7,6 +7,10 @@
 
 
 namespace rack {
+
+
+/** MIDI driver
+*/
 namespace midi {
 
 

include/network.hpp

@@ -4,6 +4,10 @@
 
 
 namespace rack {
+
+
+/** Networking functions for HTTP requests, URLs, and downloads
+*/
 namespace network {
 
 

include/plugin.hpp

@@ -7,6 +7,10 @@
 
 
 namespace rack {
+
+
+/** Plugin loader and plugin manager
+*/
 namespace plugin {
 
 

include/random.hpp

@@ -4,6 +4,10 @@
 
 
 namespace rack {
+
+
+/** Random number generator
+*/
 namespace random {
 
 
@@ -11,6 +15,7 @@ namespace random {
 void init();
 /** Returns a uniform random uint32_t from 0 to UINT32_MAX */
 uint32_t u32();
+/** Returns a uniform random uint64_t from 0 to UINT64_MAX */
 uint64_t u64();
 /** Returns a uniform random float in the interval [0.0, 1.0) */
 float uniform();

include/string.hpp

@@ -3,6 +3,10 @@
 
 
 namespace rack {
+
+
+/** Supplemental `std::string` functions
+*/
 namespace string {
 
 

include/system.hpp

@@ -4,20 +4,33 @@
 
 
 namespace rack {
+
+
+/** Cross-platform functions for operating systems routines
+*/
 namespace system {
 
 
+/** Returns a list of all entries (directories, files, symbols) in a directory. */
 std::list<std::string> listEntries(const std::string &path);
+/** Returns whether the given path is a file. */
 bool isFile(const std::string &path);
+/** Returns whether the given path is a directory. */
 bool isDirectory(const std::string &path);
+/** Copies a file. */
 void copyFile(const std::string &srcPath, const std::string &destPath);
+/** Creates a directory.
+The parent directory must exist.
+*/
 void createDirectory(const std::string &path);
-
+/** Returns the number of logical simultaneous multithreading (SMT) (e.g. Intel Hyperthreaded) threads on the CPU. */
 int getLogicalCoreCount();
+/** Sets a name of the current thread for debuggers and OS-specific process viewers. */
 void setThreadName(const std::string &name);
+/** Sets the current thread to be high-priority. */
 void setThreadRealTime();
+/** Returns the caller's human-readable stack trace with "\n"-separated lines. */
 std::string getStackTrace();
-
 /** Opens a URL, also happens to work with PDFs and folders.
 Shell injection is possible, so make sure the URL is trusted or hard coded.
 May block, so open in a new thread.

include/ui.hpp

@@ -4,6 +4,10 @@
 
 
 namespace rack {
+
+
+/** General user interface widgets using Blendish
+*/
 namespace ui {
 
 

include/widget/FramebufferWidget.hpp

@@ -6,7 +6,7 @@ namespace rack {
 namespace widget {
 
 
-/** Caches a widget's draw() result to a framebuffer so it is called less frequently
+/** Caches a widget's draw() result to a framebuffer so it is called less frequently.
 When `dirty` is true, its children will be re-rendered on the next call to step() override.
 Events are not passed to the underlying scene.
 */

include/widget/ObstructWidget.hpp

@@ -6,7 +6,7 @@ namespace rack {
 namespace widget {
 
 
-/** Widget that consumes recursing events without giving a chance for children to consume.
+/** A Widget that consumes recursing events without giving a chance for children to consume.
 */
 struct ObstructWidget : Widget {
 	void onHover(const event::Hover &e) override {
@@ -21,15 +21,9 @@ struct ObstructWidget : Widget {
 	void onHoverText(const event::HoverText &e) override {
 		e.consume(this);
 	}
-	void onHoverScroll(const event::HoverScroll &e) override {
-		e.consume(this);
-	}
 	void onDragHover(const event::DragHover &e) override {
 		e.consume(this);
 	}
-	void onPathDrop(const event::PathDrop &e) override {
-		e.consume(this);
-	}
 };
 
 

include/widget/OpaqueWidget.hpp

@@ -6,7 +6,7 @@ namespace rack {
 namespace widget {
 
 
-/** Widget that consumes recursing events but gives a chance for children to consume first.
+/** A Widget that consumes recursing events but gives a chance for children to consume first.
 You can of course override the events.
 You may also call OpaqueWidget::on*() from the overridden method to continue recursing/consuming the event.
 */

include/widget/OpenGlWidget.hpp

@@ -6,11 +6,15 @@ namespace rack {
 namespace widget {
 
 
+/** A FramebufferWidget that can be drawn on with OpenGL commands */
 struct OpenGlWidget : FramebufferWidget {
 	/** Draws every frame by default
-	Override this to restore the default behavior of FramebufferWidget.
+	Override this and call `FramebufferWidget::step()` to restore the default behavior of FramebufferWidget.
 	*/
 	void step() override;
+	/** Draws to the framebuffer.
+	Override to initialize, draw, and flush the OpenGL state.
+	*/
 	void drawFramebuffer() override;
 };
 

include/widget/SvgWidget.hpp

@@ -7,7 +7,7 @@ namespace rack {
 namespace widget {
 
 
-/** Draws an SVG */
+/** Draws an Svg */
 struct SvgWidget : Widget {
 	std::shared_ptr<Svg> svg;
 

include/widget/TransparentWidget.hpp

@@ -6,7 +6,7 @@ namespace rack {
 namespace widget {
 
 
-/** Widget that does not respond to events and does not pass events to children */
+/** A Widget that does not respond to events and does not pass events to children */
 struct TransparentWidget : Widget {
 	/** Override behavior to do nothing instead. */
 	void onHover(const event::Hover &e) override {}

include/widget/Widget.hpp

@@ -8,6 +8,10 @@
 
 
 namespace rack {
+
+
+/** General UI widgets
+*/
 namespace widget {
 
 
@@ -17,7 +21,9 @@ struct DrawContext {
 };
 
 
-/** A node in the 2D scene graph
+/** A node in the 2D [scene graph](https://en.wikipedia.org/wiki/Scene_graph).
+The bounding box of a Widget is a rectangle specified by `box` relative to their parent.
+The appearance is defined by overriding `draw()`, and the behavior is defined by overriding `step()` and `on*()` event handlers.
 */
 struct Widget {
 	/** Stores position and size */

include/widget/ZoomWidget.hpp

@@ -6,6 +6,7 @@ namespace rack {
 namespace widget {
 
 
+/** A Widget with a dynamic zoom level. */
 struct ZoomWidget : Widget {
 	float zoom = 1.f;
 

include/window.hpp

@@ -42,6 +42,7 @@ namespace rack {
 struct Font {
 	NVGcontext *vg;
 	int handle;
+	/** Don't call this directly but instead use `APP->window->loadFont()` */
 	Font(NVGcontext *vg, const std::string &filename);
 	~Font();
 	/** Use `APP->window->loadFont()` instead. */
@@ -51,6 +52,7 @@ struct Font {
 struct Image {
 	NVGcontext *vg;
 	int handle;
+	/** Don't call this directly but instead use `APP->window->loadImage()` */
 	Image(NVGcontext *vg, const std::string &filename);
 	~Image();
 	/** Use `APP->window->loadImage()` instead. */
@@ -59,6 +61,7 @@ struct Image {
 
 struct Svg {
 	NSVGimage *handle;
+	/** Don't call this directly but instead use `APP->window->loadSvg()` */
 	Svg(const std::string &filename);
 	~Svg();
 	/** Use `APP->window->loadSvg()` instead. */