From 057b5fbe5302b477c5a17638f07e77784f256b57 Mon Sep 17 00:00:00 2001
From: itsmattkc <itsmattkc@gmail.com>
Date: Fri, 22 Mar 2019 22:42:15 +1100
Subject: [PATCH] documentation of boolfield and buttonfield

---
 effects/fields/boolfield.h   | 49 +++++++++++++++++++++++++++++
 effects/fields/buttonfield.h | 60 ++++++++++++++++++++++++++++++++++++
 2 files changed, 109 insertions(+)

diff --git a/effects/fields/boolfield.h b/effects/fields/boolfield.h
index 8a7ce1f6f..dc933408c 100644
--- a/effects/fields/boolfield.h
+++ b/effects/fields/boolfield.h
@@ -12,18 +12,67 @@ class BoolField : public EffectField
 {
   Q_OBJECT
 public:
+  /**
+   * @brief See Effect::Effect().
+   */
   BoolField(EffectRow* parent, const QString& id);
 
+  /**
+   * @brief Get the boolean value at a given timecode
+   *
+   * A convenience function, equivalent to GetValueAt(timecode).toBool()
+   *
+   * @param timecode
+   *
+   * The timecode to retrieve the value at
+   *
+   * @return
+   *
+   * The boolean value at this timecode
+   */
   bool GetBoolAt(double timecode);
 
+  /**
+   * @brief See EffectField::CreateWidget()
+   */
   virtual QWidget* CreateWidget(QWidget *existing = nullptr) override;
+
+  /**
+   * @brief See EffectField::UpdateWidgetValue()
+   */
   virtual void UpdateWidgetValue(QWidget* widget, double timecode) override;
 
+  /**
+   * @brief See EffectField::ConvertStringToValue()
+   */
   virtual QVariant ConvertStringToValue(const QString& s) override;
+
+  /**
+   * @brief See EffectField::ConvertValueToString()
+   */
   virtual QString ConvertValueToString(const QVariant& v) override;
 signals:
+  /**
+   * @brief Emitted whenever the UI widget's boolean value has changed
+   *
+   * For any QCheckBox created through this field's CreateWidget() function, this signal is emitted any time the
+   * checkbox value changes (either through user intervention or keyframing). It is mostly useful for
+   * enabling/disabling/changing other UI elements based on the checked
+   * state of this field's value (e.g. enabling other fields if this field is checked).
+   *
+   * It is NOT a reliable signal that the value has changed at all, as it is only emitted if a widget (created
+   * from CreateWidget() ) is currently active.
+   */
   void Toggled(bool);
 private slots:
+  /**
+   * @brief Internal function connected to any QWidget made from CreateWidget() to update the value based on user input
+   *
+   * @param b
+   *
+   * The current checked state of the QWidget (QCheckBox in this case). Automatically set when this slot is connected
+   * to the QCheckBox::toggled() signal.
+   */
   void UpdateFromWidget(bool b);
 };
 
diff --git a/effects/fields/buttonfield.h b/effects/fields/buttonfield.h
index 940e458e5..38afb938d 100644
--- a/effects/fields/buttonfield.h
+++ b/effects/fields/buttonfield.h
@@ -3,26 +3,86 @@
 
 #include "../effectfield.h"
 
+/**
+ * @brief The ButtonField class
+ *
+ * A UI-type EffectField. This field is largely an EffectField wrapper around a QPushButton and provides no data that's
+ * usable in the Effect. It's primarily useful for other UI functions (e.g. showing/hiding a dialog or other UI
+ * elements). This field is not exposed to the external shader API as it requires raw C++ code to connect it to other
+ * elements.
+ *
+ * As with all widgets created from EffectField::CreateWidget(), you should never interface with the resulting widget
+ * directly (apart from adding it to a layout and deleting it when it's unnecessary). All signals/slots should pass
+ * through ButtonField instead to keep consistency with every layer involved.
+ */
 class ButtonField : public EffectField
 {
   Q_OBJECT
 public:
+  /**
+   * @brief See Effect::Effect().
+   */
   ButtonField(EffectRow* parent, const QString& string);
 
+  /**
+   * @brief Set whether this pushbutton is checkable
+   *
+   * This function is mainly a wrapper around QPushButton::setCheckable().
+   *
+   * "Checkable" means the button can be toggled between a state of being "normal" and being "pressed". In checkable
+   * mode this field still cannot be used as a value in an Effect. Instead use BoolField (which uses a QCheckBox
+   * representation) for passing values to the Effect that can only be true or false.
+   *
+   * @param c
+   *
+   * TRUE if this button should be checkable or not.
+   */
   void SetCheckable(bool c);
+
+  /**
+   * @brief See EffectField::CreateWidget()
+   */
   virtual QWidget* CreateWidget(QWidget *existing = nullptr) override;
 
 public slots:
+  /**
+   * @brief A slot for when a widget's (created and connected from CreateWidget() ) checked state is changed
+   *
+   * @param c
+   *
+   * The current checked state (automatically filled by the QPushButton::toggled() signal)
+   */
   void SetChecked(bool c);
 
 signals:
+  /**
+   * @brief A signal emitted whenever the field's internal checked state is changed
+   *
+   * Primarily used to set any connected widget's checked state to be consistent with the field's.
+   */
   void CheckedChanged(bool);
+
+  /**
+   * @brief A signal emitted whenever the checked state of a connected widget changes
+   *
+   * Any widgets associated with this field will emit this signal when their checked state changes.
+   */
   void Toggled(bool);
 
 private:
+  /**
+   * @brief Internal button text string passed to widgets created by CreateWidget()
+   */
   bool checkable_;
+
+  /**
+   * @brief Internal checked value passed to and from widgets created by CreateWidget()
+   */
   bool checked_;
 
+  /**
+   * @brief Internal button text string passed to widgets created by CreateWidget()
+   */
   QString button_text_;
 };