From 02ca4c66f7ec4d84ceeb8178bd5b45c05383eef3 Mon Sep 17 00:00:00 2001
From: Andrew Belt <andrewpbelt@gmail.com>
Date: Thu, 15 Dec 2022 11:22:39 -0500
Subject: [PATCH] Add doc comments

---
 include/widget/FramebufferWidget.hpp |  2 +-
 include/widget/OpaqueWidget.hpp      |  4 ++--
 include/widget/Widget.hpp            | 16 ++++++++++++++--
 include/widget/ZoomWidget.hpp        |  3 ++-
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/include/widget/FramebufferWidget.hpp b/include/widget/FramebufferWidget.hpp
index f12b59c0..bc0180db 100644
--- a/include/widget/FramebufferWidget.hpp
+++ b/include/widget/FramebufferWidget.hpp
@@ -13,7 +13,6 @@ struct FramebufferWidget : Widget {
 	struct Internal;
 	Internal* internal;
 
-	/** Set this to true to re-render the children to the framebuffer the next time it is drawn */
 	bool dirty = true;
 	bool bypassed = false;
 	float oversample = 1.0;
@@ -26,6 +25,7 @@ struct FramebufferWidget : Widget {
 
 	FramebufferWidget();
 	~FramebufferWidget();
+	/** Requests to re-render children to the framebuffer on the next draw(). */
 	void setDirty(bool dirty = true);
 	int getImageHandle();
 	NVGLUframebuffer* getFramebuffer();
diff --git a/include/widget/OpaqueWidget.hpp b/include/widget/OpaqueWidget.hpp
index ce75b729..418b5657 100644
--- a/include/widget/OpaqueWidget.hpp
+++ b/include/widget/OpaqueWidget.hpp
@@ -6,8 +6,8 @@ namespace rack {
 namespace widget {
 
 
-/** A Widget that stops propagation of all recursive PositionEvents but gives a chance for children to consume first.
-Also consumes Hover and Button for left-clicks.
+/** A Widget that stops propagation of all recursive PositionEvents (such as ButtonEvent) but gives a chance for children to consume first.
+Also consumes HoverEvent and ButtonEvent for left-clicks.
 */
 struct OpaqueWidget : Widget {
 	void onHover(const HoverEvent& e) override {
diff --git a/include/widget/Widget.hpp b/include/widget/Widget.hpp
index f7dfd564..68c93fcf 100644
--- a/include/widget/Widget.hpp
+++ b/include/widget/Widget.hpp
@@ -36,21 +36,28 @@ struct Widget : WeakBase {
 	virtual ~Widget();
 
 	math::Rect getBox();
+	/** Calls setPosition() and then setSize(). */
 	void setBox(math::Rect box);
 	math::Vec getPosition();
+	/** Sets position and triggers RepositionEvent if position changed. */
 	void setPosition(math::Vec pos);
 	math::Vec getSize();
+	/** Sets size and triggers ResizeEvent if size changed. */
 	void setSize(math::Vec size);
 	widget::Widget* getParent();
 	bool isVisible();
+	/** Sets `visible` and triggers ShowEvent or HideEvent if changed. */
 	void setVisible(bool visible);
+	/** Makes Widget visible and triggers ShowEvent if changed. */
 	void show() {
 		setVisible(true);
 	}
+	/** Makes Widget not visible and triggers HideEvent if changed. */
 	void hide() {
 		setVisible(false);
 	}
 
+	/** Requests this Widget's parent to delete it in the next step(). */
 	void requestDelete();
 
 	/** Returns the smallest rectangle containing this widget's children (visible and invisible) in its local coordinates.
@@ -119,10 +126,13 @@ struct Widget : WeakBase {
 	void addChildBelow(Widget* child, Widget* sibling);
 	void addChildAbove(Widget* child, Widget* sibling);
 	/** Removes widget from list of children if it exists.
+	Triggers RemoveEvent of child.
 	Does not delete widget but transfers ownership to caller
 	*/
 	void removeChild(Widget* child);
-	/** Removes and deletes all children */
+	/** Removes and deletes all child Widgets.
+	Triggers RemoveEvent of all children.
+	*/
 	void clearChildren();
 
 	/** Advances the module by one frame */
@@ -152,7 +162,9 @@ struct Widget : WeakBase {
 	*/
 	virtual void drawLayer(const DrawArgs& args, int layer);
 
-	/** Draws a particular child. */
+	/** Draws a particular child.
+	Saves and restores NanoVG context to prevent changing the given context.
+	*/
 	void drawChild(Widget* child, const DrawArgs& args, int layer = 0);
 
 	// Events
diff --git a/include/widget/ZoomWidget.hpp b/include/widget/ZoomWidget.hpp
index 0043d7f2..34bcd6b4 100644
--- a/include/widget/ZoomWidget.hpp
+++ b/include/widget/ZoomWidget.hpp
@@ -6,7 +6,7 @@ namespace rack {
 namespace widget {
 
 
-/** A Widget with a dynamic zoom level. */
+/** Resizes the scale of appearance and PositionEvents of children. */
 struct ZoomWidget : Widget {
 	/** Use setZoom() and getZoom() instead of using this variable directly. */
 	float zoom = 1.f;
@@ -15,6 +15,7 @@ struct ZoomWidget : Widget {
 	float getRelativeZoom(Widget* ancestor) override;
 	math::Rect getViewport(math::Rect r) override;
 	float getZoom();
+	/** Sets zoom scale and triggers DirtyEvent recursively if scale is changed, so children FramebufferWidgets are redrawn. */
 	void setZoom(float zoom);
 	void draw(const DrawArgs& args) override;
 	void drawLayer(const DrawArgs& args, int layer) override;