Improve namespace documentation.

Author: AndrewBelt

docs/index.md

@@ -1,3 +1,2 @@
-This documentation is generated by Doxygen from docstrings in header files and might not include certain functions, macros, and structures that are present in header files.
-
-It is highly recommended to instead refer to the header files themselves as a true reference.
+This documentation is generated by [Doxygen](https://www.doxygen.nl/index.html) as a convenience to Rack plugin developers and might not include certain functions, macros, and structures that are present in header files.
+It is therefore recommended to refer to Rack's header files as a true reference.

docs/logo.png

@@ -9,7 +9,7 @@
 namespace rack {
 
 
-/** Rack-specific GUI widgets and functions that control and offer feedback for the rack state.
+/** Rack's custom UI widgets that control the Rack state and engine.
 */
 namespace app {
 

include/app/common.hpp

@@ -15,6 +15,8 @@ struct Module;
 } // namespace engine
 
 
+/** Handles common path locations.
+*/
 namespace asset {
 
 

include/asset.hpp

@@ -10,7 +10,7 @@
 namespace rack {
 
 
-/** Audio driver
+/** Abstraction for all audio drivers in Rack
 */
 namespace audio {
 

include/audio.hpp

@@ -161,6 +161,8 @@ namespace std {
 #endif
 
 
+/** Root namespace for the Rack API
+*/
 namespace rack {
 
 
@@ -193,8 +195,9 @@ T* construct(F f, V v, Args... args) {
 }
 
 
-/** Defers code until the scope is destructed
-From http://www.gingerbill.org/article/defer-in-cpp.html
+/** Defers running code until the scope is destructed
+
+From http://www.gingerbill.org/article/defer-in-cpp.html.
 Example:
 
 	file = fopen(...);

include/common.hpp

@@ -14,14 +14,9 @@
 
 namespace rack {
 
-/** Component Library by [Grayscale](https://grayscale.info/).
+/** Library of Rack components: knobs, ports, lights, switches, buttons, etc.
 
-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 [email protected] for more information about licensing or the VCV Store.
+See LICENSE.md for legal details about using Rack component graphics in your Rack plugin.
 */
 namespace componentlibrary {
 

include/componentlibrary.hpp

@@ -29,7 +29,8 @@ struct Scene;
 } // namespace app
 
 
-/** Contains the application state  */
+/** Rack instance state
+*/
 struct Context {
 	widget::EventState* event = NULL;
 	app::Scene* scene = NULL;

include/context.hpp

@@ -3,7 +3,7 @@
 
 namespace rack {
 
-/** Updates Discord "now playing" status with its IPC API
+/** Updates Discord "now playing" status with IPC
 */
 namespace discord {
 

include/discord.hpp

@@ -7,7 +7,7 @@
 namespace rack {
 
 
-/** Digital signal processing routines
+/** Digital signal processing routines and classes
 */
 namespace dsp {
 

include/dsp/common.hpp

@@ -8,6 +8,8 @@
 
 
 namespace rack {
+/** High-performance classes handling modules and voltage signals between them
+*/
 namespace engine {
 
 

include/engine/Engine.hpp

@@ -19,7 +19,8 @@ struct CableWidget;
 } // namespace app
 
 
-/** Undo history actions for the Rack application */
+/** Action history for UI undo/redo
+*/
 namespace history {
 
 

include/history.hpp

@@ -7,7 +7,7 @@
 namespace rack {
 
 
-/** Synchronizes plugins with the VCV Library and updates Rack itself
+/** Synchronizes plugins with the VCV Library and handles VCV accounts with the vcvrack.com API
 */
 namespace library {
 

include/library.hpp

@@ -18,7 +18,7 @@ will print something like
 namespace rack {
 
 
-/** Logs messages to a file or the console with decoration
+/** Logs messages to a file or the terminal
 */
 namespace logger {
 

include/logger.hpp

@@ -8,7 +8,7 @@
 namespace rack {
 
 
-/** Supplemental `<cmath>` functions and types
+/** Extends `<cmath>` with extra functions and types
 */
 namespace math {
 

include/math.hpp

@@ -11,7 +11,7 @@
 namespace rack {
 
 
-/** MIDI driver
+/** Abstraction for all MIDI drivers in Rack
 */
 namespace midi {
 

include/midi.hpp

@@ -9,7 +9,7 @@
 namespace rack {
 
 
-/** Networking functions for HTTP requests, URLs, and downloads
+/** Networking functions for HTTP requests, downloads, and URLs
 */
 namespace network {
 

include/network.hpp

@@ -9,7 +9,7 @@
 namespace rack {
 
 
-/** Loads and manages plugins
+/** Loads and manages Rack plugins
 */
 namespace plugin {
 

include/plugin.hpp

@@ -7,7 +7,7 @@
 namespace rack {
 
 
-/** Random number generator
+/** Random number generation
 */
 namespace random {
 
@@ -86,7 +86,7 @@ struct Xoroshiro128Plus {
 };
 
 
-// Easy random API
+// Simple random API
 
 /** Initializes the thread-local RNG state.
 Must call when creating a thread, otherwise random state is undefined (might always return 0).

include/random.hpp

@@ -15,7 +15,8 @@
 namespace rack {
 
 
-/** Process-level globals. */
+/** Process-scope globals, most of which are persisted to a file
+*/
 namespace settings {
 
 

include/settings.hpp

@@ -6,7 +6,8 @@
 namespace rack {
 
 
-/** Abstraction of byte-aligned values for SIMD CPU acceleration. */
+/** Abstraction of aligned types for SIMD computation
+*/
 namespace simd {
 
 

include/simd/vector.hpp

@@ -7,7 +7,7 @@
 namespace rack {
 
 
-/** Cross-platform functions for operating systems routines
+/** Cross-platform functions for operating system, file path, and filesystem routines
 */
 namespace system {
 

include/system.hpp

@@ -5,6 +5,8 @@
 
 
 namespace rack {
+/** Tags describing the functions of modules
+*/
 namespace tag {
 
 

include/tag.hpp

@@ -16,7 +16,7 @@
 namespace rack {
 
 
-/** General user interface widgets using Blendish
+/** Common graphical user interface widgets
 */
 namespace ui {
 

include/ui/common.hpp

@@ -12,7 +12,7 @@
 namespace rack {
 
 
-/** General UI widgets
+/** Basic UI widget types
 */
 namespace widget {
 
@@ -494,7 +494,7 @@ struct Widget : WeakBase {
 } // namespace widget
 
 /** Deprecated Rack v1 event namespace.
-Use `FooEvent` (defined in widget::Widget) instead of `event::Foo` in new code.
+Use events defined in the widget::Widget class instead of this `event::` namespace in new code.
 */
 namespace event {
 using Base = widget::BaseEvent;
@@ -533,4 +533,5 @@ using Show = widget::Widget::ShowEvent;
 using Hide = widget::Widget::HideEvent;
 }
 
+
 } // namespace rack