documented (nearly) ever class

app/project/item/folder/folder.cpp

@@ -31,3 +31,8 @@ Item::Type Folder::type() const
 {
   return kFolder;
 }
+
+bool Folder::CanHaveChildren() const
+{
+  return true;
+}

app/project/item/folder/folder.h

@@ -26,7 +26,8 @@
 /**
  * @brief The Folder class representing a directory in a project structure
  *
- *
+ * The Item base class already has support for children, but this functionality is disabled by default
+ * (see CanHaveChildren() override). The Folder is a specific type that enables this functionality.
  */
 class Folder : public Item
 {
@@ -35,6 +36,8 @@ public:
 
   virtual Type type() const override;
 
+  virtual bool CanHaveChildren() const override;
+
 private:
 
 };

app/project/item/footage/audiostream.h

@@ -28,6 +28,9 @@ extern "C" {
 #include "rational.h"
 #include "stream.h"
 
+/**
+ * @brief A Stream derivative containing audio-specific information
+ */
 class AudioStream : public Stream
 {
 public:

app/project/item/footage/footage.h

@@ -29,6 +29,13 @@
 #include "project/item/footage/videostream.h"
 #include "rational.h"
 
+/**
+ * @brief A reference to an external media file with metadata in a project structure
+ *
+ * Footage objects serve two purposes: storing metadata about external media and storing it as a project item.
+ * Footage objects store a list of Stream objects which store the majority of video/audio metadata. These streams
+ * are identical to the stream data in the files.
+ */
 class Footage : public Item
 {
 public:

app/project/item/footage/stream.h

@@ -26,9 +26,9 @@
 class Footage;
 
 /**
- * @brief The Stream class
+ * @brief A base class for keeping metadata about a media stream.
  *
- * A base class for keeping metadata about a media stream. A Stream can contain video data, audio data, subtitle data,
+ * A Stream can contain video data, audio data, subtitle data,
  * etc. and a Stream object stores metadata about it.
  *
  * The Stream class is fairly simple and is intended to be subclassed for data that pertains specifically to one

app/project/item/footage/videostream.h

@@ -24,6 +24,9 @@
 #include "rational.h"
 #include "stream.h"
 
+/**
+ * @brief A Stream derivative containing video-specific information
+ */
 class VideoStream : public Stream
 {
 public:

app/project/item/item.cpp

@@ -115,3 +115,8 @@ Item *Item::parent() const
 {
   return parent_;
 }
+
+bool Item::CanHaveChildren() const
+{
+  return false;
+}

app/project/item/item.h

@@ -29,6 +29,12 @@
 class Item;
 using ItemPtr = std::shared_ptr<Item>;
 
+/**
+ * @brief A base-class representing any element in a Project
+ *
+ * Project objects implement a parent-child hierarchy of Items that can be used throughout the Project. The Item class
+ * itself is abstract and will need to be subclassed to be used in a Project.
+ */
 class Item
 {
 public:
@@ -88,6 +94,8 @@ public:
 
   Item *parent() const;
 
+  virtual bool CanHaveChildren() const;
+
 private:
   QList<ItemPtr> children_;
 

app/project/project.h

@@ -27,12 +27,13 @@
 #include "project/item/folder/folder.h"
 
 /**
- * @brief The Project class
+ * @brief A project instance containing all the data pertaining to the user's project
  *
- * A project instance containing all the data pertaining to the user's project, including:
+ * A project instance uses a parent-child hierarchy of Item objects. Projects will usually contain the following:
  *
  * * Footage
  * * Sequences
+ * * Folders
  * * Project Settings
  * * Window Layout
  */

app/project/projectviewmodel.cpp

@@ -182,7 +182,7 @@ bool ProjectViewModel::hasChildren(const QModelIndex &parent) const
     // Check if this item is a kFolder type
     // If it's a folder, we always return TRUE in order to always show the "expand triangle" icon,
     // even when there are no "physical" children
-    if (item->type() == Item::kFolder) {
+    if (item->CanHaveChildren()) {
       return true;
     }
   }
@@ -216,7 +216,7 @@ bool ProjectViewModel::canFetchMore(const QModelIndex &parent) const
     // Check if this item is a kFolder type
     // If it's a folder, we always return TRUE in order to always show the "expand triangle" icon,
     // even when there are no "physical" children
-    if (item->type() == Item::kFolder) {
+    if (item->CanHaveChildren()) {
       return true;
     }
   }
@@ -232,7 +232,11 @@ Qt::ItemFlags ProjectViewModel::flags(const QModelIndex &index) const
     return Qt::ItemIsDropEnabled;
   }
 
-  Qt::ItemFlags f = Qt::ItemIsDragEnabled | Qt::ItemIsDropEnabled | QAbstractItemModel::flags(index);
+  Qt::ItemFlags f = Qt::ItemIsDragEnabled | QAbstractItemModel::flags(index);
+
+  if (GetItemObjectFromIndex(index)->CanHaveChildren()) {
+    f |= Qt::ItemIsDropEnabled;
+  }
 
   // If the column is the kName column, that means it's editable
   if (columns_.at(index.column()) == kName) {
@@ -308,7 +312,7 @@ bool ProjectViewModel::dropMimeData(const QMimeData *data, Qt::DropAction action
     Item* drop_location = GetItemObjectFromIndex(drop);
 
     // If this is not a folder, we cannot drop these items here
-    if (drop_location->type() != Item::kFolder) {
+    if (!drop_location->CanHaveChildren()) {
       return false;
     }
 
@@ -365,7 +369,7 @@ bool ProjectViewModel::dropMimeData(const QMimeData *data, Qt::DropAction action
     Item* drop_item = GetItemObjectFromIndex(drop);
 
     // If we didn't drop onto an item, find the nearest parent folder (should eventually terminate at root either way)
-    while (drop_item->type() != Item::kFolder) {
+    while (!drop_item->CanHaveChildren()) {
       drop_item = drop_item->parent();
     }
 

app/project/projectviewmodel.h

@@ -27,9 +27,12 @@
 #include "project.h"
 
 /**
- * @brief The ProjectViewModel class
+ * @brief An adapter that interprets the data in a Project into a Qt item model for usage in ViewModel Views.
  *
- * An adapter that interprets the data in a Project into a Qt item model for usage in ViewModel Views.
+ * Assuming a Project is currently "open" (i.e. the Project is connected to a ProjectExplorer/ProjectPanel through
+ * a ProjectViewModel), it may be better to make modifications (e.g. additions/removals/renames) through the
+ * ProjectViewModel so that the views can be efficiently and correctly updated. ProjectViewModel contains several
+ * "wrapper" functions for Project and Item functions that also signal any connected views to update accordingly.
  */
 class ProjectViewModel : public QAbstractItemModel
 {