From 52151a709da5bf73df8193732a539d6565f6c91b Mon Sep 17 00:00:00 2001 From: Andrew Belt Date: Sun, 10 Feb 2019 23:52:32 -0500 Subject: [PATCH] Add various API documentation --- docs/Makefile | 3 +++ include/app.hpp | 2 ++ include/app/ModuleWidget.hpp | 1 + include/app/ParamQuantity.hpp | 2 +- include/app/ParamWidget.hpp | 1 + include/app/PortWidget.hpp | 1 + include/app/RackWidget.hpp | 1 + include/audio.hpp | 4 ++++ include/color.hpp | 3 +++ include/component.hpp | 10 ++++++++++ include/dsp/common.hpp | 4 ++++ include/engine/Module.hpp | 2 +- include/event.hpp | 2 ++ include/gamepad.hpp | 4 ++++ include/history.hpp | 1 + include/keyboard.hpp | 4 ++++ include/logger.hpp | 8 +++++++- include/math.hpp | 4 ++++ include/midi.hpp | 4 ++++ include/network.hpp | 4 ++++ include/plugin.hpp | 4 ++++ include/random.hpp | 5 +++++ include/string.hpp | 4 ++++ include/system.hpp | 17 +++++++++++++++-- include/ui.hpp | 4 ++++ include/widget/FramebufferWidget.hpp | 2 +- include/widget/ObstructWidget.hpp | 8 +------- include/widget/OpaqueWidget.hpp | 2 +- include/widget/OpenGlWidget.hpp | 6 +++++- include/widget/SvgWidget.hpp | 2 +- include/widget/TransparentWidget.hpp | 2 +- include/widget/Widget.hpp | 8 +++++++- include/widget/ZoomWidget.hpp | 1 + include/window.hpp | 3 +++ 34 files changed, 115 insertions(+), 18 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 5664f8ca..db1b87dc 100644 --- a/docs/Makefile +++ b/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 diff --git a/include/app.hpp b/include/app.hpp index 9a7bde08..142f36d5 100644 --- a/include/app.hpp +++ b/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 { diff --git a/include/app/ModuleWidget.hpp b/include/app/ModuleWidget.hpp index 97303d47..1d71da90 100644 --- a/include/app/ModuleWidget.hpp +++ b/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 */ diff --git a/include/app/ParamQuantity.hpp b/include/app/ParamQuantity.hpp index 922820b1..edd1cca2 100644 --- a/include/app/ParamQuantity.hpp +++ b/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; diff --git a/include/app/ParamWidget.hpp b/include/app/ParamWidget.hpp index 43e76a54..0a631018 100644 --- a/include/app/ParamWidget.hpp +++ b/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; diff --git a/include/app/PortWidget.hpp b/include/app/PortWidget.hpp index 60b7ef8d..2c1dc426 100644 --- a/include/app/PortWidget.hpp +++ b/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; diff --git a/include/app/RackWidget.hpp b/include/app/RackWidget.hpp index 06622623..56acfc56 100644 --- a/include/app/RackWidget.hpp +++ b/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; diff --git a/include/audio.hpp b/include/audio.hpp index f0e0a2c6..59ab47d0 100644 --- a/include/audio.hpp +++ b/include/audio.hpp @@ -11,6 +11,10 @@ namespace rack { + + +/** Audio driver +*/ namespace audio { diff --git a/include/color.hpp b/include/color.hpp index 161b5a41..669fa708 100644 --- a/include/color.hpp +++ b/include/color.hpp @@ -5,6 +5,9 @@ namespace rack { + +/** Utilities for `NVGcolor` +*/ namespace color { diff --git a/include/component.hpp b/include/component.hpp index b79795b0..9fe44ab1 100644 --- a/include/component.hpp +++ b/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 { diff --git a/include/dsp/common.hpp b/include/dsp/common.hpp index dc447f85..570d0d61 100644 --- a/include/dsp/common.hpp +++ b/include/dsp/common.hpp @@ -3,6 +3,10 @@ namespace rack { + + +/** Digital signal processing routines for plugins +*/ namespace dsp { diff --git a/include/engine/Module.hpp b/include/engine/Module.hpp index ca636484..16e4db7f 100644 --- a/include/engine/Module.hpp +++ b/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() {} diff --git a/include/event.hpp b/include/event.hpp index f584a986..b7ab78ac 100644 --- a/include/event.hpp +++ b/include/event.hpp @@ -12,6 +12,8 @@ namespace widget { } // namespace widget +/** Event state machine for Widgets +*/ namespace event { diff --git a/include/gamepad.hpp b/include/gamepad.hpp index d7a827bd..52b7ab39 100644 --- a/include/gamepad.hpp +++ b/include/gamepad.hpp @@ -3,6 +3,10 @@ namespace rack { + + +/** Gamepad/joystick/controller MIDI driver +*/ namespace gamepad { diff --git a/include/history.hpp b/include/history.hpp index 2cfc39ad..8e13b01c 100644 --- a/include/history.hpp +++ b/include/history.hpp @@ -16,6 +16,7 @@ namespace app { } // namespace app +/** Undo history actions for the Rack application */ namespace history { diff --git a/include/keyboard.hpp b/include/keyboard.hpp index b850d669..b6353a70 100644 --- a/include/keyboard.hpp +++ b/include/keyboard.hpp @@ -3,6 +3,10 @@ namespace rack { + + +/** Computer keyboard MIDI driver +*/ namespace keyboard { diff --git a/include/logger.hpp b/include/logger.hpp index af717e91..a35a2e23 100644 --- a/include/logger.hpp +++ b/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, ...); diff --git a/include/math.hpp b/include/math.hpp index 5d338ef0..a89ce8ed 100644 --- a/include/math.hpp +++ b/include/math.hpp @@ -4,6 +4,10 @@ namespace rack { + + +/** Supplemental `` functions and types +*/ namespace math { diff --git a/include/midi.hpp b/include/midi.hpp index 3d4d647e..15b58422 100644 --- a/include/midi.hpp +++ b/include/midi.hpp @@ -7,6 +7,10 @@ namespace rack { + + +/** MIDI driver +*/ namespace midi { diff --git a/include/network.hpp b/include/network.hpp index c50badd4..f6d9dcd8 100644 --- a/include/network.hpp +++ b/include/network.hpp @@ -4,6 +4,10 @@ namespace rack { + + +/** Networking functions for HTTP requests, URLs, and downloads +*/ namespace network { diff --git a/include/plugin.hpp b/include/plugin.hpp index 1c6b19ed..f30655da 100644 --- a/include/plugin.hpp +++ b/include/plugin.hpp @@ -7,6 +7,10 @@ namespace rack { + + +/** Plugin loader and plugin manager +*/ namespace plugin { diff --git a/include/random.hpp b/include/random.hpp index 8aa53e13..23af5a22 100644 --- a/include/random.hpp +++ b/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(); diff --git a/include/string.hpp b/include/string.hpp index 14a4cfd0..a71832e2 100644 --- a/include/string.hpp +++ b/include/string.hpp @@ -3,6 +3,10 @@ namespace rack { + + +/** Supplemental `std::string` functions +*/ namespace string { diff --git a/include/system.hpp b/include/system.hpp index 6ebcae56..a57651a2 100644 --- a/include/system.hpp +++ b/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 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. diff --git a/include/ui.hpp b/include/ui.hpp index 95003fa0..162703f0 100644 --- a/include/ui.hpp +++ b/include/ui.hpp @@ -4,6 +4,10 @@ namespace rack { + + +/** General user interface widgets using Blendish +*/ namespace ui { diff --git a/include/widget/FramebufferWidget.hpp b/include/widget/FramebufferWidget.hpp index f43d38b6..a80c42d5 100644 --- a/include/widget/FramebufferWidget.hpp +++ b/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. */ diff --git a/include/widget/ObstructWidget.hpp b/include/widget/ObstructWidget.hpp index 8bdd6098..19211a37 100644 --- a/include/widget/ObstructWidget.hpp +++ b/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); - } }; diff --git a/include/widget/OpaqueWidget.hpp b/include/widget/OpaqueWidget.hpp index 6cbaaa95..dc14c0c3 100644 --- a/include/widget/OpaqueWidget.hpp +++ b/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. */ diff --git a/include/widget/OpenGlWidget.hpp b/include/widget/OpenGlWidget.hpp index 1562ae99..084931de 100644 --- a/include/widget/OpenGlWidget.hpp +++ b/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; }; diff --git a/include/widget/SvgWidget.hpp b/include/widget/SvgWidget.hpp index 12a4f9ec..6419bae4 100644 --- a/include/widget/SvgWidget.hpp +++ b/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; diff --git a/include/widget/TransparentWidget.hpp b/include/widget/TransparentWidget.hpp index 9b0c32c2..80637fff 100644 --- a/include/widget/TransparentWidget.hpp +++ b/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 {} diff --git a/include/widget/Widget.hpp b/include/widget/Widget.hpp index a7ebaf05..8e8b65cd 100644 --- a/include/widget/Widget.hpp +++ b/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 */ diff --git a/include/widget/ZoomWidget.hpp b/include/widget/ZoomWidget.hpp index 0e4aa38d..a3979c6e 100644 --- a/include/widget/ZoomWidget.hpp +++ b/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; diff --git a/include/window.hpp b/include/window.hpp index e167170d..fcc687fb 100644 --- a/include/window.hpp +++ b/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. */