documented (nearly) ever class

app/widget/menu/menu.h

@@ -24,24 +24,129 @@
 #include <QMenuBar>
 #include <QMenu>
 
+/**
+ * @brief A menu widget for context menus and menu bars
+ *
+ * A QMenu subclass with functions for creating menus and menu items that conform to Olive's menu and keyboard shortcut
+ * system.
+ *
+ * In Olive, menu items in the menu bar are also responsible for keyboard shortcuts throughout the application. To allow
+ * these to be configurable and these configurations saveable, every item needs a unique ID. This ID gets linked to the
+ * keyboard shortcuts in config files. The ID doesn't get translated so it can also persist through language changes.
+ *
+ * The ID gets stored in the QAction's "id" property. If a keyboard shortcut is provided, it gets stored in the
+ * QAction's "keydefault" property.
+ *
+ * It is always recommended to use this over QMenu in any situation.
+ */
 class Menu : public QMenu
 {
 public:
+  /**
+   * @brief Construct a Menu and add it to a QMenuBar
+   *
+   * This Menu can be connected to a slot that's triggered when the Menu is "about to show". Use `receiver` and
+   * `member` to connect this (same syntax as QObject::connect) or leave as nullptr to not.
+   */
   Menu(QMenuBar* bar, const QObject* receiver = nullptr, const char* member = nullptr);
+
+  /**
+   * @brief Construct a Menu and add it as a submenu to another Menu
+   *
+   * This Menu can be connected to a slot that's triggered when the Menu is "about to show". Use `receiver` and
+   * `member` to connect this (same syntax as QObject::connect) or leave as nullptr to not.
+   */
   Menu(Menu* bar, const QObject* receiver = nullptr, const char* member = nullptr);
 
+  /**
+   * @brief Create a menu item and add it to this menu
+   *
+   * @param id
+   *
+   * The action's unique ID
+   *
+   * @param receiver
+   *
+   * The QObject to receive the signal when this item is triggered
+   *
+   * @param member
+   *
+   * The QObject slot to connect this action's triggered signal to
+   *
+   * @param key
+   *
+   * Default keyboard sequence
+   *
+   * @return
+   *
+   * The QAction that was created and added to this Menu
+   */
   QAction* AddItem(const QString& id,
                    const QObject* receiver,
                    const char* member,
                    const QString &key = QString());
 
+  /**
+   * @brief Create a menu item
+   *
+   * @param parent
+   *
+   * The QAction's parent
+   *
+   * @param id
+   *
+   * The action's unique ID
+   *
+   * @param receiver
+   *
+   * The QObject to receive the signal when this item is triggered
+   *
+   * @param member
+   *
+   * The QObject slot to connect this action's triggered signal to
+   *
+   * @param key
+   *
+   * Default keyboard sequence
+   *
+   * @return
+   *
+   * The QAction that was created and added to this Menu
+   */
   static QAction* CreateItem(QObject* parent,
                              const QString& id,
                              const QObject* receiver,
                              const char* member,
                              const QString& key = QString());
 
-  static void ConformItem(QAction *a, const QString& id,
+  /**
+   * @brief Conform a QAction to Olive's ID/keydefault system
+   *
+   * If a QAction was created elsewhere (e.g. through QUndoStack::createUndoAction()), this function will give it
+   * properties conforming it to Olive's menu item system
+   *
+   * @param a
+   *
+   * The QAction's to conform
+   *
+   * @param id
+   *
+   * The action's unique ID
+   *
+   * @param receiver
+   *
+   * The QObject to receive the signal when this item is triggered
+   *
+   * @param member
+   *
+   * The QObject slot to connect this action's triggered signal to
+   *
+   * @param key
+   *
+   * Default keyboard sequence
+   */
+  static void ConformItem(QAction *a,
+                          const QString& id,
                           const QObject* receiver,
                           const char* member,
                           const QString& key = QString());

app/widget/menu/menushared.h

@@ -23,6 +23,9 @@
 
 #include "widget/menu/menu.h"
 
+/**
+ * @brief A static object that provides various "stock" menus for use throughout the application
+ */
 class MenuShared : public QObject {
 public:
   MenuShared();

app/widget/panel/panel.h

@@ -25,9 +25,7 @@
 #include <QEvent>
 
 /**
- * @brief The PanelWidget class
- *
- * A widget that is always dockable within the MainWindow.
+ * @brief A widget that is always dockable within the MainWindow.
  */
 class PanelWidget : public QDockWidget {
   Q_OBJECT

app/widget/playbackcontrols/playbackcontrols.h

@@ -24,18 +24,45 @@
 #include <QWidget>
 #include <QLabel>
 
+/**
+ * @brief A playback controls widget providing buttons for navigating media
+ *
+ * This widget optionally features timecode displays for the current timecode and end timecode.
+ */
 class PlaybackControls : public QWidget
 {
 public:
   PlaybackControls(QWidget* parent);
 
+  /**
+   * @brief Set whether the timecodes should be shown or not
+   */
   void SetTimecodeEnabled(bool enabled);
 
 signals:
+  /**
+   * @brief Signal emitted when "Go to Start" is clicked
+   */
   void BeginClicked();
+
+  /**
+   * @brief Signal emitted when "Previous Frame" is clicked
+   */
   void PrevFrameClicked();
+
+  /**
+   * @brief Signal emitted when "Play/Pause" is clicked
+   */
   void PlayClicked();
+
+  /**
+   * @brief Signal emitted when "Next Frame" is clicked
+   */
   void NextFrameClicked();
+
+  /**
+   * @brief Signal emitted when "Go to End" is clicked
+   */
   void EndClicked();
 
 private:

app/widget/projectexplorer/projectexplorer.cpp

@@ -162,7 +162,7 @@ void ProjectExplorer::DoubleClickViewSlot(const QModelIndex &index)
     Item* i = static_cast<Item*>(index.internalPointer());
 
     // If the item is a folder, browse to it
-    if (i->type() == Item::kFolder
+    if (i->CanHaveChildren()
         && (view_type() == olive::ListView || view_type() == olive::IconView)) {
 
       BrowseToFolder(index);
@@ -261,10 +261,10 @@ Folder *ProjectExplorer::GetSelectedFolder()
     Item* sel_item = selected_items.at(i);
 
     // If this item is not a folder, presumably it's parent is
-    if (sel_item->type() != Item::kFolder) {
+    if (!sel_item->CanHaveChildren()) {
       sel_item = sel_item->parent();
 
-      Q_ASSERT(sel_item->type() == Item::kFolder);
+      Q_ASSERT(sel_item->CanHaveChildren());
     }
 
     if (folder == nullptr) {

app/widget/projectexplorer/projectexplorer.h

@@ -34,9 +34,7 @@
 #include "widget/projectexplorer/projectexplorernavigation.h"
 
 /**
- * @brief A widget for browsing through Project classes
- *
- * A widget for browsing through a Project structure.
+ * @brief A widget for browsing through a Project structure.
  *
  * ProjectExplorer automatically handles the view<->model system using a ProjectViewModel. Therefore, all that needs to
  * be provided is the Project structure itself.

app/widget/projectexplorer/projectexplorerdefines.h

@@ -3,9 +3,13 @@
 
 namespace olive {
 
+/// The minimum size an icon in ProjectExplorer can be
 const int kProjectIconSizeMinimum = 16;
+
+/// The maximum size an icon in ProjectExplorer can be
 const int kProjectIconSizeMaximum = 256;
 
+/// The default size an icon in ProjectExplorer can be
 const int kProjectIconSizeDefault = 64;
 
 }

app/widget/projectexplorer/projectexplorericonviewitemdelegate.h

@@ -23,6 +23,9 @@
 
 #include <QStyledItemDelegate>
 
+/**
+ * @brief The delegate that's used to draw items when ProjectExplorer is in Icon view
+ */
 class ProjectExplorerIconViewItemDelegate : public QStyledItemDelegate {
 public:
   ProjectExplorerIconViewItemDelegate(QObject *parent = nullptr);

app/widget/projectexplorer/projectexplorerlistview.h

@@ -24,6 +24,9 @@
 #include "projectexplorerlistviewbase.h"
 #include "projectexplorerlistviewitemdelegate.h"
 
+/**
+ * @brief The view widget used when ProjectExplorer is in List View
+ */
 class ProjectExplorerListView : public ProjectExplorerListViewBase
 {
   Q_OBJECT

app/widget/projectexplorer/projectexplorerlistviewbase.h

@@ -23,6 +23,10 @@
 
 #include <QListView>
 
+/**
+ * @brief A QListView derivative that contains functionality used by both List view and Icon view (which are both based
+ * on QListView)
+ */
 class ProjectExplorerListViewBase : public QListView
 {
   Q_OBJECT

app/widget/projectexplorer/projectexplorertreeview.h

@@ -24,7 +24,7 @@
 #include <QTreeView>
 
 /**
- * @brief The ProjectExplorerTreeView class
+ * @brief The view widget used when ProjectExplorer is in Tree View
  *
  * A fairly simple subclass of QTreeView that provides a double clicked signal whether the index is valid or not
  * (QAbstractItemView has a doubleClicked() signal but it's only emitted with a valid index).

app/widget/taskview/taskview.h

@@ -26,6 +26,14 @@
 
 #include "widget/taskview/taskviewitem.h"
 
+/**
+ * @brief A widget that shows a list of Tasks
+ *
+ * TaskView is a fairly simple widget for showing TaskViewItem widgets that each represent a Task object. The main
+ * entry point is the slot AddTask() which should be connected to a TaskManager's TaskAdded() signal. No more connecting
+ * is necessary since TaskViewItem will automatically delete itself (thus removing itself from the TaskView) when the
+ * Task finishes.
+ */
 class TaskView : public QScrollArea
 {
   Q_OBJECT
@@ -33,6 +41,11 @@ public:
   TaskView(QWidget* parent);
 
 public slots:
+  /**
+   * @brief Creates a TaskViewItem, connects it to a Task, and adds it to this widget
+   *
+   * Connect this to TaskManager::TaskAdded().
+   */
   void AddTask(Task* t);
 
 private:

app/widget/taskview/taskviewitem.h

@@ -28,12 +28,28 @@
 
 #include "task/task.h"
 
+/**
+ * @brief A widget that visually represents the status of a Task
+ *
+ * The TaskViewItem widget shows a description of the Task (Task::text(), a progress bar (updated by
+ * Task::ProgressChanged), the Task's status (text generated from Task::status() or Task::error()), and provides
+ * a cancel button (triggering Task::Cancel()) for cancelling a Task before it finishes.
+ *
+ * The main entry point is SetTask() after a Task and TaskViewItem objects are created.
+ */
 class TaskViewItem : public QFrame
 {
   Q_OBJECT
 public:
   TaskViewItem(QWidget* parent);
 
+  /**
+   * @brief Connects a Task to this object
+   *
+   * If a Task has already been connected, this will disconnect this TaskViewItem from the previously connected
+   * Task before connecting to the next one - however there are very few circumstances where this would be necessary
+   * since TaskViewItem is designed to delete itself when a Task is complete.
+   */
   void SetTask(Task* t);
 
 private:

app/widget/toolbar/toolbar.h

@@ -28,9 +28,9 @@
 #include "tool/tool.h"
 
 /**
- * @brief The Toolbar class
+ * @brief A widget containing buttons for all of Olive's application-wide tools.
  *
- * A widget containing buttons for all of Olive's application-wide tools. Buttons are displayed in a FlowLayout that
+ * Buttons are displayed in a FlowLayout that
  * adjusts and wraps (like text) depending on the widget's size.
  *
  * By default, this Toolbar is not connected to anything. It's recommended to connect SLOT(SetTool()) and

app/widget/toolbar/toolbarbutton.h

@@ -26,9 +26,7 @@
 #include "tool/tool.h"
 
 /**
- * @brief The ToolbarButton class
- *
- * Simple derived class of QPushButton to contain an Tool ID. Used as the main widget through Toolbar.
+ * @brief Simple derived class of QPushButton to contain an Tool ID. Used as the main widget through Toolbar.
  */
 class ToolbarButton : public QPushButton
 {

app/widget/viewer/viewer.h

@@ -29,9 +29,7 @@
 #include "widget/playbackcontrols/playbackcontrols.h"
 
 /**
- * @brief The ViewerWidget class
- *
- * An OpenGL-based viewer widget with playback controls.
+ * @brief An OpenGL-based viewer widget with playback controls (a PlaybackControls widget).
  */
 class ViewerWidget : public QWidget
 {

app/widget/viewer/viewerglwidget.h

@@ -26,10 +26,10 @@
 #include "render/gl/shaderptr.h"
 
 /**
- * @brief The ViewerGLWidget class
+ * @brief The inner display/rendering widget of a Viewer class.
  *
- * The inner display/rendering widget of a Viewer class. Actual rendering/composition occurs elsewhere offscreen and
- * multithreaded, so its main purpose is receiving an OpenGL texture to display it.
+ * Actual composition occurs elsewhere offscreen and
+ * multithreaded, so its main purpose is receiving a finalized OpenGL texture and displaying it.
  *
  * The main entry point is SetTexture() which will receive an OpenGL texture ID, store it, and then call update() to
  * draw it on screen. The drawing function is in paintGL() (called during the update() process by Qt) and is fairly