Merge pull request #5 from Merctrans/feature/documentation

feature/documentation

local-addons/morons/models/contributor.py

@@ -7,7 +7,49 @@
 
 # uncomment and create a view for it
 class InternalUser(models.Model):
-    """MercTrans Internal Users"""
+    """
+    A model for managing internal users at MercTrans.
+
+    This class extends the 'res.users' model from Odoo, specifically tailored for 
+    the needs of MercTrans. It includes additional fields to store information 
+    about the users' roles, contact details, nationality, payment methods, and 
+    educational background. This class is crucial for managing internal users' 
+    data, from basic identification details to more specific information like 
+    payment methods and educational qualifications.
+
+    Attributes:
+        General:
+            _inherit (str): Inherited model name in the Odoo framework.
+            contributor (fields.Boolean): Field to indicate if the user is a contributor.
+            active (fields.Boolean): Field to indicate if the user account is active.
+            currency (fields.Many2one): Relation to 'res.currency' to set the user's preferred currency.
+            skype (fields.Char): Field for the user's Skype ID.
+            nationality (fields.Many2many): Relation to 'res.lang' to represent the user's nationality.
+            country_of_residence (fields.Many2one): Relation to 'res.country' for the user's country of residence.
+            timezone (fields.Selection): Selection field for the user's timezone.
+
+        Payment Methods:
+            paypal (fields.Char): Field for the user's PayPal ID.
+            transferwise_id (fields.Char): Field for the user's Wise ID.
+            bank_account_number (fields.Char): Field for the user's bank account number.
+            bank_name (fields.Char): Field for the name of the user's bank.
+            iban (fields.Char): Field for the user's IBAN.
+            swift (fields.Char): Field for the user's SWIFT code.
+            bank_address (fields.Char): Field for the user's bank address.
+            preferred_payment_method (fields.Selection): Selection field for the user's preferred payment method.
+
+        Education and Experience:
+            dates_attended (fields.Date): Field for the dates the user attended educational institutions.
+            school (fields.Char): Field for the name of the school the user attended.
+            field_of_study (fields.Char): Field for the user's field of study.
+            year_obtained (fields.Selection): Selection field for the year the user obtained their degree.
+            certificate (fields.Char): Field for the name of any certificate obtained by the user.
+
+    Methods:
+        _tz_get(): Returns a list of all timezones for the timezone selection field.
+        validate_email(): Validates the format of the user's email for PayPal and login.
+    """
+
     _inherit = ["res.users"]
 
     contributor = fields.Boolean(string='Contributor', default=False)
@@ -20,11 +62,11 @@ class InternalUser(models.Model):
     #                             string='Timezone',
     #                             required=True,
     #                             default=lambda self: self.env.user.tz or 'UTC')
-    #
+
     # @api.model
     # def _tz_get(self):
     #     return [(x, x) for x in pytz.all_timezones]
-    #
+
     # # Payment Methods
     # paypal = fields.Char('PayPal ID')
     # transferwise_id = fields.Char('Wise ID')
@@ -36,7 +78,7 @@ class InternalUser(models.Model):
     # preferred_payment_method = fields.Selection(selection=[('paypal', 'Paypal'),
     #                                                        ('transferwise', 'Wise'),
     #                                                        ('bank', 'Bank Transfer')])
-    #
+
     # @api.constrains('paypal')
     # def validate_email(self):
     #     if self.paypal:
@@ -45,14 +87,14 @@ class InternalUser(models.Model):
     #             self.paypal)
     #         if match is None:
     #             raise ValidationError('Not a valid email')
-    #
+
     # # Education and Experience
     # dates_attended = fields.Date('Date Attended')
     # school = fields.Char('School')
     # field_of_study = fields.Char('Field of Study')
     # year_obtained = fields.Selection([(num, str(num)) for num in range(1900, datetime.datetime.now().year + 1)], 'Year')
     # certificate = fields.Char('Certificate')
-    #
+
     # @api.constrains('login')
     # def validate_email(self):
     #     if self.login:

local-addons/morons/models/project.py

@@ -11,6 +11,22 @@
 
 
 class MercTransServices(models.Model):
+    """
+    A model representing the different services offered by MercTrans.
+
+    This class encapsulates the various services that MercTrans provides, 
+    categorized into different departments. It serves as a way to manage 
+    and access the services information in an organized manner.
+
+    Attributes:
+        _name (str): Internal name of the model in the Odoo framework.
+        _rec_name (str): Field to use for record name.
+        _description (str): A brief description of the model's purpose.
+        department_list (list of tuples): A predefined list of departments.
+        department (fields.Selection): Field for selecting a department from the department_list.
+        name (fields.Char): Field for the name of the service.
+    """
+
     _name = "merctrans.services"
     _rec_name = "name"
     _description = "Services offered by MercTrans"
@@ -25,6 +41,41 @@ class MercTransServices(models.Model):
 
 
 class MerctransProject(models.Model):
+    """
+    A model representing projects managed by MercTrans.
+
+    This class extends the functionality of the 'project.project' model 
+    to cater specifically to the needs of MercTrans projects. It includes 
+    features such as different work units, payment statuses, and calculation 
+    of project values and margins. It also handles the creation of unique 
+    project IDs and the computation of various financial metrics.
+
+    Attributes:
+        _inherit (list): Inherited model name in the Odoo framework.
+        work_unit_list (list of tuples): A predefined list of work units for projects.
+        payment_status_list (list of tuples): A predefined list of payment statuses.
+        job_id (fields.Char): Field for the unique project identifier.
+        service (fields.Many2many): Relationship to the 'merctrans.services' model.
+        source_language (fields.Many2one): Field for the source language of the project.
+        target_language (fields.Many2many): Field for the target languages of the project.
+        discount (fields.Integer): Field for any discount applied to the project.
+        work_unit (fields.Selection): Field for selecting a work unit from the work_unit_list.
+        volume (fields.Integer): Field for the volume of the project.
+        currency_id (fields.Many2one): Field for the currency used in the project.
+        sale_rate (fields.Float): Field for the sale rate of the project.
+        job_value (fields.Monetary): Computed field for the total value of the project.
+        payment_status (fields.Selection): Field for the payment status of the project.
+        po_value (fields.Monetary): Computed field for the Purchase Order value of the project.
+        margin (fields.Float): Computed field for the margin of the project.
+
+    Methods:
+        create(vals): Creates a new project with a unique ID.
+        _compute_job_value(): Computes the job value based on volume, sale rate, and discount.
+        _compute_po_value(): Computes the PO value from all associated tasks.
+        _compute_margin(): Calculates the project margin.
+        _compute_receivable(): Calculates the receivable of the project.
+    """
+
     _inherit = ["project.project"]
 
     work_unit_list = [
@@ -93,6 +144,17 @@ class MerctransProject(models.Model):
 
     @api.model
     def create(self, vals):
+        """Creates a new project.
+
+            This method creates a new project and assigns it a unique project ID. 
+            It is automatically triggered when a new project is created.
+
+            Parameters:
+                vals: A dictionary containing the values of the fields on the project.
+
+            Returns:
+                project: The newly created project.
+        """
         if vals.get("job_id", "New") == "New":
             vals["job_id"] = self.env["ir.sequence"].next_by_code(
                 "increment_project_id"
@@ -102,25 +164,61 @@ def create(self, vals):
 
     @api.depends("volume", "sale_rate", "discount")
     def _compute_job_value(self):
+        """Computes the job value of the project.
+
+            Parameters:
+                volume: The volume of the project.
+                sale_rate: The sale rate of the project.
+                discount: The discount of the project (if any).
+
+            Returns:
+                None: Updates the 'job_value' field of each project record with the calculated job value.
+        """
         for project in self:
             project.job_value = (
                     (100 - project.discount) / 100 * project.volume * project.sale_rate
             )
 
     @api.depends('tasks')
     def _compute_po_value(self):
+        """Computes the total Purchase Order (PO) value of the project.
+
+            Parameters:
+                tasks: The tasks associated with the project.
+
+            Returns:
+                None: Updates the 'po_value' field of each project record with the calculated sum.
+        """
         for project in self:
             if project.tasks:
                 project.po_value = sum(po.po_value for po in project.tasks)
 
     @api.depends('po_value', 'job_value')
     def _compute_margin(self):
+        """Computes the margin of the project.
+
+            Parameters:
+                po_value: The total PO value of the project.
+                job_value: The total job value of the project.
+
+            Returns:
+                None: Updates the 'margin' field of each project record with the calculated margin.
+        """
         for project in self:
             if project.job_value and project.po_value:
                 project.margin = (project.job_value - project.po_value) / project.job_value
 
     @api.depends('po_value', 'job_value')
     def _compute_receivable(self):
+        """Computes the receivable of the project.
+
+            Parameters:
+                po_value: The total PO value of the project.
+                job_value: The total job value of the project.
+
+            Returns:
+                None: Updates the 'receivable' field of each project record with the calculated receivable.
+        """
         for project in self:
             if project.po_value and project.job_value:
                 project.receivable = project.job_value - project.po_value
@@ -129,6 +227,37 @@ def _compute_receivable(self):
 
 
 class MerctransTask(models.Model):
+    """
+    A model representing tasks within Merctrans projects.
+
+    This class extends the 'project.task' model of Odoo, tailored for the specific needs of 
+    Merctrans projects. It includes functionality for managing purchase order statuses, work units, 
+    payment statuses, and various other task-related details. Key features include the ability to 
+    compute the value of tasks based on volume and rate, and handling the source and target languages 
+    for tasks in translation projects.
+
+    Attributes:
+        _inherit (str): Inherited model name in the Odoo framework.
+        po_status_list (list of tuples): A predefined list of possible statuses for purchase orders.
+        work_unit_list (list of tuples): A predefined list of work units applicable to tasks.
+        payment_status_list (list of tuples): A predefined list of payment statuses for tasks.
+        rate (fields.Float): Field for the rate applicable to the task.
+        service (fields.Many2many): Relationship to the 'merctrans.services' model, indicating services involved in the task.
+        source_language (fields.Many2one): Computed field for the source language of the task, derived from the associated project.
+        target_language (fields.Many2many): Field for the target languages of the task.
+        work_unit (fields.Selection): Field for selecting a work unit from the work_unit_list.
+        volume (fields.Integer): Field for the volume of work associated with the task.
+        po_value (fields.Float): Computed field for the Purchase Order value of the task.
+        payment_status (fields.Selection): Field for the payment status of the task.
+        currency (fields.Char): Computed field for the currency used in the task.
+
+    Methods:
+        _invert_get_source_lang(): Placeholder method for inverse computation of source language. (TODO)
+        _invert_get_target_lang(): Placeholder method for inverse computation of target language.  (TODO)
+        _compute_po_value(): Computes the Purchase Order value of the task based on volume and rate.
+        _get_source_lang(): Computes the source language of the task based on its associated project.
+        _compute_currency_id(): Computes the currency used in the task based on the users assigned to it.
+    """
     _inherit = "project.task"
 
     po_status_list = [