Refactoring and documentation

LenaPi/models/NavigationItemModel.h

@@ -3,6 +3,16 @@
 
 #include <QObject>
 
+/**
+ * @brief Model for navigation item.
+ *
+ * Each item represents a directory that is specified by path.
+ * It contains a reference to its parent item as well as to its children.
+ * Each directory contains an image named image.jpg that is displayed on
+ * on the list delegate.
+ * A delegate is circular if it has children and rectangular if it is
+ * a leaf, i.e., if it represents a music folder.
+ */
 class NavigationItemModel : public QObject
 {
     Q_OBJECT
@@ -16,34 +26,89 @@ signals:
     void clicked();
 
 public:
-    NavigationItemModel(QObject *parent = Q_NULLPTR);
+    explicit NavigationItemModel(QObject *parent = nullptr);
 
+    /**
+     * @brief Get source of image displayed on delegate.
+     * @return Source of image
+     *
+     * The image must be named image.jpg and must be postioned in the directory
+     * represented by this item. If no such image is found, a default image is displayed
+     * on the delegate.
+     */
     QString getImageSource() const;
 
+    /**
+     * @brief Get path to folder represented by this navigation item.
+     * @return Path to folder
+     */
     QString getPath() const;
+    /**
+     * @brief Set folder path and set image source displayed on delegate.
+     * @param path Path to directory that is represented by this navigation item.
+     * @return returns false if directory specified by path does not exist
+     */
     bool setPath(const QString & path);
 
+    /**
+     * @brief Indicates whether this item is displayed as a circular or default delegate in navigation list.
+     * @return true if the current item is displayed as a circular delegate.
+     *
+     * An item is displayed as a circular delegate if it has children.
+     */
     bool isCircleDelegate() const;
-    void setCircleDelegate(bool value);
 
+    /**
+     * @brief Indicates whether the current item is the root item of the navigation.
+     * @return true if the current item is the root item.
+     */
     bool isRoot() const;
+    /**
+     * @brief Get pointer to parent item.
+     * @return Pointer to parent item.
+     */
     NavigationItemModel* getParentItem();
 
+    /**
+     * @brief Indicates whether the current item has children.
+     * @return false if children list is empty, true otherwise.
+     */
     bool hasChildren() const;
+    /**
+     * @brief Get all child items
+     * @return List of child items
+     */
     QList<NavigationItemModel *> getChildren();
 
+    /**
+     * @brief Get all siblings, i.e., all children of parent item.
+     * @return List of all siblings
+     */
     QList<NavigationItemModel *> getSiblings();
 
+    /**
+     * @brief Append a child
+     * @param item Child item.
+     */
     void appendChild(NavigationItemModel* item);
+    /**
+     * @brief Remove all child items.
+     *
+     * Will delete children via deleteLater
+     */
     void clearChildren();
 
-    Q_INVOKABLE void onClicked();
+public slots:
+    /**
+     * @brief Defines behavior on clicking the current navigation item. Emits the clicked-signal.
+     */
+    void onClicked();
 
 private:
     QString mPath = QString("");
     QString mImageSource;
 
-    QList<NavigationItemModel*> mChildren = QList<NavigationItemModel*>();
+    QList<NavigationItemModel*> mChildren;
     NavigationItemModel* mParentItem;
 };