Refactoring and documentation

LenaPi/models/NavigationItemModel.cpp

@@ -69,7 +69,7 @@ QList<NavigationItemModel *> NavigationItemModel::getChildren()
 QList<NavigationItemModel *> NavigationItemModel::getSiblings()
 {
     if(isRoot()){
-        return QList<NavigationItemModel*>();
+        return QList<NavigationItemModel *>();
     } else{
         return mParentItem->getChildren();
     }

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;
 };
 

LenaPi/models/NavigationListModel.cpp

@@ -1,18 +1,13 @@
 #include "NavigationListModel.h"
-
 #include "NavigationItemModel.h"
 
-NavigationListModel::NavigationListModel(QObject* parent) : QObject(parent)
-{
-  /*nothing*/
-}
 
-QList<QObject *> NavigationListModel::getModelItems()
+ QList<QObject*> NavigationListModel::getModelItems()
 {
     return mItems;
 }
 
-void NavigationListModel::setModelItems(QList<NavigationItemModel *> list)
+void NavigationListModel::setModelItems(const QList<NavigationItemModel*>& list)
 {
     mItems.clear();
     for(const auto& item : list){

LenaPi/models/NavigationListModel.h

@@ -5,20 +5,24 @@
 
 class NavigationItemModel;
 
+/**
+ * @brief Model containing navigation items and handling navigation.
+ * @todo Check whether we can use QAbstractListModel here!
+ */
 class NavigationListModel : public QObject
 {
     Q_OBJECT
-    Q_PROPERTY(QList<QObject*> pModelItems READ getModelItems NOTIFY modelItemsChanged)
+    Q_PROPERTY( QList<QObject*> pModelItems READ getModelItems NOTIFY modelItemsChanged)
     Q_PROPERTY(bool pIsBackVisible READ isBackVisible NOTIFY modelItemsChanged)
 
 signals:
     void modelItemsChanged();
 
 public:
-    NavigationListModel(QObject* parent = Q_NULLPTR);
+    explicit NavigationListModel(QObject* parent = nullptr) : QObject(parent) { /* nothing */ }
 
     QList<QObject*> getModelItems();
-    void setModelItems(QList<NavigationItemModel*> list);
+    void setModelItems(const QList<NavigationItemModel*>& list);
 
     bool isBackVisible();
 

LenaPi/models/UiStateModel.h

@@ -4,6 +4,12 @@
 #include <QObject>
 #include <QUrl>
 
+/**
+ * @brief Handles state of UI by providing the qml source.
+ *
+ * Provides the possibility to switch between different
+ * ui states such as music player or navigation.
+ */
 class UiStateModel : public QObject
 {
     Q_OBJECT
@@ -14,7 +20,7 @@ signals:
     void sourceChanged();
 
 public:
-    UiStateModel(QObject *parent = Q_NULLPTR);
+    explicit UiStateModel(QObject *parent = nullptr);
 
     QUrl getSource() const;