Docs: Update documentation

src/core/downloaderdialog.cpp

@@ -291,17 +291,19 @@ DownloaderDialog::selectDownload(DownloadType type, QPair<int, int> info)
   QModelIndex task;
   if (type == Recitation) {
     parent = m_treeModel.index(info.first, 0);
-    task = m_treeModel.index(info.second - 1, 1, parent);
+    task = m_treeModel.index(info.second - 1, 0, parent);
   } else if (type == QCF) {
     parent = m_treeModel.index(m_treeModel.rowCount() - 1, 0);
     task = m_treeModel.index(0, 0, parent);
   } else if (type == File) {
     parent = m_treeModel.index(m_treeModel.rowCount() - 2 - !info.first, 0);
-    // tafsir
+    // remove default db indices from current index as defaults are not
+    // downloadable
     if (!info.first)
+      // tafsir
       info.second -= info.second > 6;
-    // translation
     else
+      // translation
       info.second -= 1 + info.second > 5;
     task = m_treeModel.index(info.second, 0, parent);
   }

src/core/downloaderdialog.h

@@ -66,11 +66,16 @@ public slots:
    */
   void downloadAborted();
   /**
-   * MODIFIED
+   * @brief Update UI elements on download group completion
+   * @param type - DownloadType of the download group
+   * @param metainfo - QList of download group information
    */
   void downloadCompleted(DownloadType type, const QList<int>& metainfo);
   /**
-   * MODIFIED
+   * @brief Callback function to update UI elements when the current active
+   * download group fails
+   * @param type - DownloadType of the download group
+   * @param metainfo - QList of download group information
    */
   void topTaskDownloadError(DownloadType type, const QList<int>& metainfo);
   /**
@@ -81,7 +86,9 @@ public slots:
    */
   void updateDownloadSpeed(int value, QString unit);
   /**
-   * MODIFIED
+   * @brief automatically select a group/task to download
+   * @param type - DownloadType of the download group to select
+   * @param info - metainfo for the download task
    */
   void selectDownload(DownloadType type,
                       QPair<int, int> info = QPair<int, int>(0, 1));
@@ -127,7 +134,10 @@ private slots:
    */
   void populateTreeModel();
   /**
-   * MODIFIED
+   * @brief adds a QFrame of download task info and a progressbar
+   * @param type - DownloadType of the download group to select
+   * @param info - download metainfo QPair used by DownloadType::Recitation and
+   * DownloadType::File
    */
   void addTaskProgress(DownloadType type,
                        QPair<int, int> info = QPair<int, int>(-1, -1));

src/core/mainwindow.cpp

@@ -1350,21 +1350,11 @@ MainWindow::updateSideFont()
 void
 MainWindow::updateVerseType()
 {
-  int idx = m_settings->value("Reader/VerseType").toInt();
-  switch (idx) {
-    case 0:
-      m_versesFont.setFamily(m_activeQuranBrowser->pageFont());
-      break;
-    case 1:
-      m_versesFont.setFamily("kfgqpc_hafs_uthmanic _script");
-      break;
-    case 2:
-      m_versesFont.setFamily("Emine");
-      break;
-  }
-
+  VerseType type =
+    qvariant_cast<VerseType>(m_settings->value("Reader/VerseType"));
+  m_versesFont.setFamily(Globals::verseFontname(type, m_currVerse.page));
   m_versesFont.setPointSize(m_settings->value("Reader/VerseFontSize").toInt());
-  m_dbMgr->setVerseType(static_cast<VerseType>(idx));
+  m_dbMgr->setVerseType(type);
 }
 
 Verse

src/core/mainwindow.h

@@ -186,11 +186,12 @@ private slots:
    */
   void missingRecitationFileWarn(int reciterIdx, int surah);
   /**
-   * MODIFIED
+   * @brief display a warning messagebox when QCF2 files are not found
    */
   void missingQCF();
   /**
-   * MODIFIED
+   * @brief display a warning messagebox when a tafsir db file is not found
+   * @param idx - index of tafsir in Globals::tafasirList
    */
   void missingTafsir(int idx);
   /**
@@ -266,9 +267,7 @@ private slots:
    */
   void toggleReaderView();
   /**
-   * @brief togglePlayerControls
-   *
-   * MODIFIED
+   * @brief toggle the visibility of the player controls in the main window
    */
   void togglePlayerControls();
   /**
@@ -335,7 +334,8 @@ private slots:
    */
   void updateSideFont();
   /**
-   * MODIFIED
+   * @brief Updates the type of the verses shown and reload the font family and
+   * size
    */
   void updateVerseType();
   /**
@@ -619,13 +619,11 @@ private slots:
    */
   VerseFrame* m_highlightedFrm = nullptr;
   /**
-   * @brief m_betaqaViewer
-   *
-   * MODIFIED
+   * @brief pointer to the surah card (betaqa) widget
    */
   BetaqaViewer* m_betaqaViewer = nullptr;
   /**
-   * @brief m_verseDlg
+   * @brief pointer to the votd dialog
    */
   VerseDialog* m_verseDlg = nullptr;
   /**

src/core/settingsdialog.h

@@ -141,7 +141,8 @@ public slots:
 
 signals:
   /**
-   * MODIFIED
+   * @fn qcf2Missing()
+   * @brief signal emitted when one of the 604 QCF2 files is missing
    */
   void qcf2Missing();
   /**
@@ -185,7 +186,8 @@ public slots:
    */
   void sideFontChanged();
   /**
-   * MODIFIED
+   * @fn verseTypeChanged()
+   * @brief signal emitted when the type shown changes
    */
   void verseTypeChanged();
   /**
@@ -240,7 +242,8 @@ public slots:
    */
   void fillLanguageCombobox();
   /**
-   * MODIFIED
+   * @brief reload all tafsir and translation options to show all available
+   * files and sets the shown index to the selected one
    */
   void updateContentCombobox();
   /**
@@ -253,13 +256,12 @@ public slots:
    */
   void checkShortcuts();
   /**
-   * MODIFIED
+   * @brief check if QCF2 font files exist
+   *
+   * @return true - all 604 QCF2 files are found
+   * @return false - one of the files is missing
    */
   bool qcfExists();
-  /**
-   * MODIFIED
-   */
-  bool tafsirExists(int idx);
   /**
    * @brief QCF font size used in constructing Quran page.
    */

src/globals.h

@@ -69,8 +69,7 @@ struct Reciter
 };
 /**
  * @brief Tafsir struct contains data about a single tafsir
- *
- * MODIFIED
+ * @details tafasir are stored in the resource file "files.xml"
  */
 struct Tafsir
 {

src/main.cpp

@@ -86,8 +86,8 @@ checkSettingsGroup(QSettings* settings, int group);
 void
 populateRecitersList();
 /**
- *
- * MODIFIED
+ * @brief populates the global tafasir and translation lists with data from
+ * files.xml
  */
 void
 populateContentLists();

src/utils/dbmanager.h

@@ -179,7 +179,9 @@ class DBManager : public QObject
    */
   QString getSurahName(const int sIdx, bool ar = false);
   /**
-   * MODIFIED
+   * @brief get the surah card (betaqa) content
+   * @param surah - surah number
+   * @return QString of the surah card text
    */
   QString getBetaqa(const int surah);
   /**
@@ -304,17 +306,13 @@ class DBManager : public QObject
    */
   void setActiveKhatmah(const int id);
   /**
-   * @brief setVerseType
+   * @brief Set the VerseType shown
    * @param newVerseType
-   *
-   * MODIFIED
    */
   void setVerseType(VerseType newVerseType);
   /**
-   * @brief getVerseType
-   * @return
-   *
-   * MODIFIED
+   * @brief getter for m_verseType
+   * @return VerseType
    */
   VerseType getVerseType() const;
 

src/utils/downloadmanager.h

@@ -29,17 +29,24 @@ class DownloadManager : public QObject
 public:
   /**
    * @brief DownloadTask struct represents a single verse file download task
-   * @details Quran surahs are downloaded as separate verse mp3 files which are
-   * represented as DownloadTask instances
-   *
-   * MODIFIED
+   * @details downloads are separated into 3 different types
+   * DownloadType::Recitation - MP3 recitation for a single verse - reciter
+   * combination
+   * DownloadType::QCF - QCF v2 font files
+   * DownloadType::File - single file download, used for downloading tafsir and
+   * translation DB files
    */
   struct DownloadTask
   {
     /**
      * @brief metainfo vector for storing information about the download task
-     * @details in case of a regular verse download, { reciter, surah, verse }
-     * and in case of QCF font download, { -1, -1, page }
+     * @details data in the metainfo QList depends on the DownloadType
+     * DownloadType::Recitation - { reciter, surah, verse }
+     * DownloadType::QCF - { -1, -1, page }
+     * DownloadType::File - { k, idx, bytes } where
+     * k: kind of file (0 for tafsir, 1 for translation)
+     * idx: index of the file in its corresponding global QList
+     * bytes: is the current number of bytes downloaded (updated automatically)
      */
     QList<int> metainfo;
     /**
@@ -100,18 +107,20 @@ public slots:
    */
   void processTaskQueue();
   /**
-   * @brief process the surah queue which contains surahs to be downloaded, add
-   * DownloadTask instance for each verse of the processed surah
-   *
-   * MODIFIED
+   * @brief process the download group queue by adding appropriate download
+   * tasks according to the DownloadType and metainfo
    */
   void processDownloadQueue();
   /**
-   * MODIFIED
+   * @brief enqueues an entry in the download group queue
+   * @param type - DownloadType of group
+   * @param info - additional info of the download required
    */
   void addToQueue(DownloadType type, QPair<int, int> info = { -1, -1 });
   /**
-   * MODIFIED
+   * @brief overload to enqueue a Recitation entry in the download group queue
+   * @param reciter - reciter index in Globals::recitersList
+   * @param surah - surah number to download
    */
   void addToQueue(int reciter, int surah);
   /**
@@ -161,9 +170,7 @@ public slots:
   void downloadSpeedUpdated(int valuePerSec, QString unit);
   /**
    * @fn void downloadCompleted(int, int)
-   * @brief Emitted when all surah download tasks are completed
-   *
-   * MODIFIED
+   * @brief Emitted when the currently active download group is completed
    */
   void downloadCompleted(DownloadType type, const QList<int>& metainfo);
   /**
@@ -195,16 +202,12 @@ public slots:
                    const int surah,
                    const int verse) const;
   /**
-   * @brief enqeueQCFTasks
-   *
-   * MODIFIED
+   * @brief enqueues QCF font file tasks
    */
   void enqeueQCF();
   /**
-   * @brief enqeueFile
-   * @param tafsiridx
-   *
-   * MODIFIED
+   * @brief enqueues a File task based on the given info
+   * @param info
    */
   void enqeueTask(QPair<int, int> info);
   /**
@@ -229,9 +232,8 @@ public slots:
    */
   bool m_isDownloading = false;
   /**
-   * @brief the verse count of the current surah being downloaded
-   *
-   * MODIFIED
+   * @brief the total count of files in the current group download / total bytes
+   * if downloading a single file
    */
   int m_activeTotal;
   QNetworkRequest m_versionReq;
@@ -249,21 +251,16 @@ public slots:
    */
   DownloadTask m_activeTask;
   /**
-   * @brief m_activeType
-   *
-   * MODIFIED
+   * @brief currently active DownloadType
    */
   DownloadType m_activeType = Recitation;
   /**
-   * @brief surah download queue
-   *
-   * MODIFIED
+   * @brief download group queue, used for quickly adding downloads that will be
+   * expanding into separate DownloadTask (s) when its processed
    */
   QQueue<QPair<DownloadType, QPair<int, int>>> m_downloadQueue;
   /**
-   * @brief individual verses download queue
-   *
-   * MODIFIED
+   * @brief individual DownloadTask queue
    */
   QQueue<DownloadTask> m_taskQueue;
   /**

src/widgets/quranpagebrowser.h

@@ -171,14 +171,12 @@ public slots:
    */
   QImage surahFrame(int surah);
   /**
-   * @brief Set the Href object
-   *
-   * @param cursor
-   * @param to
-   * @param url
-   * @return int
-   *
-   * MODIFIED
+   * @brief utility to set the href url for the text from the current cursor
+   * position to the position given
+   * @param cursor - pointer to the current QTextCursor used for inserting text
+   * @param to  - the position in document to stop at
+   * @param url - url to set for the selected portion
+   * @return int - the current cursor postion
    */
   int setHref(QTextCursor* cursor, int to, QString url);
   /**