Adding documentation comments for doxygen (#1)

lib/DB/AddressModel.py

@@ -1,17 +1,63 @@
+"""! @brief Defines the model class to handle addresses."""
+##
+# @file AddressModel.py
+#
+# @brief Defines the AddressModel class.
+#
+# @section description_addressmodel Description
+# Defines the model class to handle CRUD operations on addresses.
+# - AddressModel (Model class)
+#
+# @section libraries_addressmodel 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/Qt.html">Qt</a> PySid6 core Class
+#   - A namespace contains miscellaneous identifiers used throughout the Qt library.
+# - <a href="">AddressDAO</a> Local class
+#   -  Defines the low-lever DAO class to handle CRUD operations on addresses.
+#
+# @section notes_addressmodel Notes
+# - None.
+#
+# @section todo_addressmodel TODO
+# - None.
+#
+# @section author_addressmodel 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 QAbstractListModel, Qt, Slot, QModelIndex
 from .AddressDAO import AddressDAO
 from ..PyqcrmDataRoles import PyqcrmDataRoles
 
 class AddressModel(QAbstractListModel):
-
+    """! The AddressModel class.
+    Defines a model class utilized to handle data.
+    Inherits from QAbstractListModel
+    Handles the address data operations.
+    """
     def __init__(self):
+        """! The AddressModel class initializer.
+        """
         super().__init__()
         self.__address_data = AddressDAO().getAddressData()
 
     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.__address_data)
 
     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>
+        """
         row = index.row()
         if role == Qt.DisplayRole:
             data = self.__address_data[row][2]
@@ -22,6 +68,9 @@ class AddressModel(QAbstractListModel):
         return None
 
     def roleNames(self):
+        """! Returns the model’s role names.
+        Ref. <a href="https://doc.qt.io/qtforpython-6/PySide6/QtCore/QAbstractItemModel.html#PySide6.QtCore.QAbstractItemModel.roleNames">roleNames()</a>
+        """
         return {
             Qt.DisplayRole: b"display",
             PyqcrmDataRoles.CITY_ROLE: b"city",
@@ -32,6 +81,11 @@ class AddressModel(QAbstractListModel):
 
     @Slot(bool, str)
     def getAddresses(self, all, zipcode):
+        """! Loads the addresses from the storage backend.
+        @param all Boolean to specify whether all addresses to be returned or not.
+        @param zipcode String to look up addresses following a specific zipcode.
+        @return Returns a dictionary containing the addresses.
+        """
         data = AddressDAO().getAddressData(all, zipcode)
         return data