documented node view classes

app/widget/nodeview/nodeview.h

@@ -27,27 +27,80 @@
 #include "widget/nodeview/nodeviewedge.h"
 #include "widget/nodeview/nodeviewitem.h"
 
+/**
+ * @brief A widget for viewing and editing node graphs
+ *
+ * This widget takes a NodeGraph object and constructs a QGraphicsScene representing its data, viewing and allowing
+ * the user to make modifications to it.
+ */
 class NodeView : public QGraphicsView
 {
   Q_OBJECT
 public:
   NodeView(QWidget* parent);
 
+  /**
+   * @brief Sets the graph to view
+   */
   void SetGraph(NodeGraph* graph);
 
+  /**
+   * @brief Retrieve the graphical widget corresponding to a specific Node
+   *
+   * In situations where you know what Node you're working with but need the UI object (e.g. for positioning), this
+   * static function will retrieve the NodeViewItem (Node UI representation) connected to this Node in a certain
+   * QGraphicsScene. This can be called from any other UI object, since it'll have a reference to the QGraphicsScene
+   * through QGraphicsItem::scene().
+   *
+   * If the scene does not contain a widget for this node (usually meaning the node's graph is not the active graph
+   * in this view/scene), this function returns nullptr.
+   */
   static NodeViewItem* NodeToUIObject(QGraphicsScene* scene, Node* n);
+
+  /**
+   * @brief Retrieve the graphical widget corresponding to a specific NodeEdge
+   *
+   * Same as NodeToUIObject() but returns a NodeViewEdge corresponding to a NodeEdgePtr instead.
+   */
   static NodeViewEdge* EdgeToUIObject(QGraphicsScene* scene, NodeEdgePtr n);
 
+  /**
+   * @brief Overloaded NodeToUIObject(QGraphicsScene* scene, Node* n) if you have direct access to a NodeView instance
+   */
+  NodeViewItem* NodeToUIObject(Node* n);
+
+  /**
+   * @brief Overloaded EdgeToUIObject(QGraphicsScene* scene, NodeEdgePtr n) if you have direct access to a NodeView instance
+   */
+  NodeViewEdge* EdgeToUIObject(NodeEdgePtr n);
+
 private:
   NodeGraph* graph_;
 
   QGraphicsScene scene_;
 
 private slots:
+  /**
+   * @brief Slot when an edge is added to a graph (SetGraph() connects this)
+   *
+   * This should NEVER be called directly, only connected to a NodeGraph. To add an edge (i.e. connect two node
+   * parameters together), use NodeParam::ConnectEdge().
+   */
   void AddEdge(NodeEdgePtr edge);
 
+  /**
+   * @brief Slot when an edge is removed from a graph (SetGraph() connects this)
+   *
+   * This should NEVER be called directly, only connected to a NodeGraph. To remove an edge (i.e. disconnect two node
+   * parameters), use NodeParam::DisconnectEdge().
+   */
   void RemoveEdge(NodeEdgePtr edge);
 
+  /**
+   * @brief Internal function triggered when any change is signalled from the QGraphicsScene
+   *
+   * Current primary function is to inform all NodeViewEdges to re-adjust in case any Nodes have moved
+   */
   void ItemsChanged();
 
 };