Adding documentation comments for doxygen (#1)

lib/DB/BusinessModel.py

@@ -1,4 +1,41 @@
-# This Python file uses the following encoding: utf-8
+"""! @brief Defines the model class to handle customers."""
+##
+# @file BusinessModel.py
+#
+# @brief Defines the BusinessModel class.
+#
+# @section description_businessmodel Description
+# Defines the model class to handle CRUD operations on customers.
+# - BusinessModel (Model class)
+#
+# @section libraries_businessmodel Libraries/Modules
+# - <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/QAbstractListModel.html">QAbstractListModel</a> PySid6 core Class
+#   - Provides an abstract model that can be subclassed to create one-dimensional list models.
+# - <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/QModelIndex.html">QModelIndex</a> PySid6 core Class
+#   - Used to locate data in a data model.
+# - <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/Slot.html">Slot</a> PySide6 function
+#   - A function that is called in response to a particular signal.
+# - <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/Signal.html">Signal</a> PySide6 class
+#   - Provides a way to declare and connect Qt signals in a pythonic way.
+# - <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/Qt.html">Qt</a> PySid6 core Class
+#   - A namespace contains miscellaneous identifiers used throughout the Qt library.
+# - <a href="">BusinessDAO</a> Local class
+#   -  Defines the low-lever DAO class to handle CRUD operations on customers.
+# - <a href="">ConfigLoader</a> Local class
+#   -  Defines the base class for the program configuration.
+#
+# @section notes_businessmodel Notes
+# - None.
+#
+# @section todo_businessmodel TODO
+# - None.
+#
+# @section author_businessmodel Author(s)
+# - Created by Linuxero on 03/14/2025.
+# - Modified by Linuxero on 03/14/2025.
+#
+# Copyright (c) 2025 Schnaxero.  All rights reserved.
+
 from PySide6.QtCore import QAbstractTableModel, QModelIndex, Qt, Slot, Signal
 from .BusinessDAO import BusinessDAO
 from ..PyqcrmFlags import PyqcrmFlags
@@ -62,6 +99,11 @@ from ..ConfigLoader import ConfigLoader
 
 
 class BusinessModel(QAbstractTableModel):
+    """! The BusinessModel class.
+    Defines a model class utilized to handle data.
+    Inherits from QAbstractListModel
+    Handles the customers data operations.
+    """
     __visible_index = {}
     __visible_columns = None
     __col_name = ""
@@ -70,6 +112,8 @@ class BusinessModel(QAbstractTableModel):
     __business_dict = {'business':{}} #,'contact':{}}
 
     def __init__(self):
+        """! The AddressModel class initializer.
+        """
         super().__init__()
         self.__business_dao = BusinessDAO()
         self.__business_dao.newBusinessAdded.connect(self.__refreshView)
@@ -78,12 +122,17 @@ class BusinessModel(QAbstractTableModel):
         self.__getData()
 
     def __getData(self, criterion = "Alle"):
+        """! Returns the customers data according to the model.
+        @param criterion String to specify which customers are to be fetched.
+        """
         self.beginResetModel()
         rows, self.__visible_columns = self.__business_dao.getBusiness(self.__key, criterion)
         self.__data = rows
         self.endResetModel()
 
     def __getBusinessInfo(self):
+        """! Fetches detailed information about a customer.
+        """
         self.__business_dict['business']['id'] = self.__business[0][0]
         self.__business_dict['business']['contactid'] = self.__business[0][1]
         self.__business_dict['business']['company'] = self.__business[0][2]
@@ -100,18 +149,30 @@ class BusinessModel(QAbstractTableModel):
         self.__business_dict['business']['city'] = self.__business[0][13]
 
     def rowCount(self, parent= QModelIndex()):
+        """! Returns the number of rows under the given parent.
+        Ref. <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/QAbstractItemModel.html#PySide6.QtCore.QAbstractItemModel.rowCount">rowCount()</a>
+        """
         return len (self.__data)
 
     def columnCount(self, parent= QModelIndex()):
+        """! Returns the number of columns for the children of the given parent.
+        Ref. <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/QAbstractItemModel.html#PySide6.QtCore.QAbstractItemModel.columnCount">columnCount()</a>
+        """
         return len(self.__visible_columns) - 1
 
     def data(self, index, role = Qt.DisplayRole):
+        """! Returns the data stored under the given role for the item referred to by the index.
+        Ref. <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/QAbstractItemModel.html#PySide6.QtCore.QAbstractItemModel.data">data()</a>
+        """
         if role == Qt.DisplayRole:
             row = self.__data[index.row()]
             return row[index.column() + 1]
         return None
 
     def headerData(self, section, orientation, role= Qt.DisplayRole):
+        """! Returns the data for the given role and section in the header with the specified orientation.
+        Ref. <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/QAbstractItemModel.html#PySide6.QtCore.QAbstractItemModel.headerData">headerData()</a>
+        """
         if orientation == Qt.Horizontal and role ==Qt.DisplayRole:
             self.__col_name = self.__visible_columns[section + 1]
             return self.__col_name
@@ -132,6 +193,9 @@ class BusinessModel(QAbstractTableModel):
 
     @Slot(int)
     def onRowClicked(self, row):
+        """! Handles a selected customer from the GUI.
+        @param row The number of the customer in the data model.
+        """
         #print(self.__data)
         #print(f"Selected table row: {row}, corresponding DB ID: {self.__data[row][0]}")
         if not self.__business_dict['business'] or self.__data[row][0] != self.__business_dict['business']['id']:
@@ -143,19 +207,31 @@ class BusinessModel(QAbstractTableModel):
 
     @Slot(result = dict)
     def getClientDetails(self):
+        """! Fetches a selected customer from the GUI.
+        @return A dictionary containing all information of a customer.
+        """
         return self.__business_dict
 
     @Slot(str)
     def viewCriterion(self, criterion):
+        """! Updates the customers view.
+        @param criterion The criterion used to look for customers.
+        """
         self.__getData(criterion)
 
 
     @Slot(dict, int)
     def addBusiness(self, business, contact_id):
+        """! Saves a customer view.
+        @param business The customer to be saved.
+        @param contact_id The contact person id if available.
+        """
         self.__business_dao.addBusiness(business, contact_id)
 
     @Slot()
     def __refreshView(self):
+        """! Updates the customers view.
+        """
         self.__getData()
 
     @Slot(dict)