[IMP] l10n_br_fiscal: doc/line/mixin docstring

Author: rvalyi

l10n_br_fiscal/models/document.py

@@ -31,22 +31,30 @@
 
 
 class Document(models.Model):
-    """Implementação base dos documentos fiscais
-
-    Devemos sempre ter em mente que o modelo que vai usar este módulo abstrato
-     tem diversos metodos importantes e a intenção que os módulos da OCA que
-     extendem este modelo, funcionem se possível sem a necessidade de
-     codificação extra.
-
-    É preciso também estar atento que o documento fiscal tem dois estados:
-
-    - Estado do documento eletrônico / não eletônico: state_edoc
-    - Estado FISCAL: state_fiscal
-
-    O estado fiscal é um campo que é alterado apenas algumas vezes pelo código
-    e é de responsabilidade do responsável fiscal pela empresa de manter a
-    integridade do mesmo, pois ele não tem um fluxo realmente definido e
-    interfere no lançamento do registro no arquivo do SPED FISCAL.
+    """
+    Base implementation for Brazilian fiscal documents.
+
+    This model serves as the foundational structure for various fiscal
+    documents within the Brazilian localization. It's designed to be
+    extensible, allowing other OCA modules to build upon it, ideally
+    minimizing the need for additional custom coding for common fiscal
+    document functionalities.
+
+    Key aspects to note:
+    - The fiscal document manages two primary states:
+        - Electronic Document State (`state_edoc`): Reflects the status
+          of the document in its electronic lifecycle (e.g., Draft,
+          Authorized, Cancelled).
+        - Fiscal State (`state_fiscal`): Represents the document's status
+          from a purely fiscal accounting perspective (e.g., Regular,
+          Cancelled for fiscal purposes). This state is less automated
+          and often managed by the fiscal responsible to ensure correct
+          reporting, such as in SPED Fiscal.
+
+    This model inherits common fields and methods from
+    `l10n_br_fiscal.document.mixin` and includes features for document
+    numbering, key validation, partner and company fiscal details, line
+    items, and workflows for subsequent document generation and returns.
     """
 
     _name = "l10n_br_fiscal.document"

l10n_br_fiscal/models/document_line.py

@@ -5,6 +5,21 @@
 
 
 class DocumentLine(models.Model):
+    """
+    Represents a line item within a Brazilian fiscal document.
+
+    This model defines the core structure of a fiscal document line,
+    primarily linking it to its parent document (`l10n_br_fiscal.document`)
+    and holding essential line-specific data like quantity and a
+    descriptive name.
+
+    The vast majority of detailed fiscal fields (e.g., product, NCM,
+    CFOP, various tax bases and values) and their complex computation
+    logic are inherited from `l10n_br_fiscal.document.line.mixin`.
+    This delegation ensures code reusability and keeps this model
+    focused on its direct relationships and core line properties.
+    """
+
     _name = "l10n_br_fiscal.document.line"
     _inherit = "l10n_br_fiscal.document.line.mixin"
     _description = "Fiscal Document Line"

l10n_br_fiscal/models/document_line_mixin.py

@@ -49,6 +49,31 @@
 
 
 class FiscalDocumentLineMixin(models.AbstractModel):
+    """
+    Provides the primary field structure for Brazilian fiscal document lines.
+
+    It is inherited by sale.order.line, purchase.order.linne, account.move.line
+    and even stock.move in separate modules.
+    Indeed these business documents need to take care of some fiscal parameters
+    before creating Fiscal Document Lines. And of course,
+    Fiscal Document Lines themselves inherit from this mixin.
+
+    This abstract model defines an extensive set of fields necessary for
+    line-item fiscal calculations and reporting in Brazil. It includes:
+    - Product and quantity information.
+    - Detailed fiscal classifications (NCM, CFOP, CEST, etc.).
+    - Fields for each specific Brazilian tax (ICMS, IPI, PIS, COFINS,
+      ISSQN, etc.), covering their respective bases, rates, and
+      calculated values.
+    - Line-level totals and cost components.
+
+    It inherits computational logic, onchange handlers, and other complex
+    methods from `l10n_br_fiscal.document.line.mixin.methods`. Models
+    that represent actual document lines (e.g.,
+    `l10n_br_fiscal.document.line`) should inherit this mixin to
+    acquire the necessary fiscal field definitions and associated behaviors.
+    """
+
     _name = "l10n_br_fiscal.document.line.mixin"
     _inherit = "l10n_br_fiscal.document.line.mixin.methods"
     _description = "Document Fiscal Mixin"

l10n_br_fiscal/models/document_line_mixin_methods.py

@@ -46,6 +46,28 @@
 
 
 class FiscalDocumentLineMixinMethods(models.AbstractModel):
+    """
+    Provides the method implementations for l10n_br_fiscal.document.line.mixin.
+
+    These methods are extracted into this separate mixin due to the way
+    l10n_br_fiscal.document.line is incorporated into account.move.line
+    by the l10n_br_account module (decorator pattern).
+
+    Specifically:
+    - In l10n_br_account, fields from l10n_br_fiscal.document.line
+      are added to account.move.line using Odoo's `_inherits` (composition)
+      mechanism.
+    - The methods in *this* mixin, however, are intended to be inherited
+      using the standard `_inherit` mechanism.
+
+    This separation is crucial because `_inherits` handles field composition
+    but does not inherit methods. Thus, `_inherit` is used to bring in
+    these methods. If these methods were defined in the same class as the
+    fields of l10n_br_fiscal.document.line.mixin (which are subject to
+    `_inherits`), and account.move.line also used `_inherit` on that
+    single class, the fields would be duplicated.
+    """
+
     _name = "l10n_br_fiscal.document.line.mixin.methods"
     _description = "Fiscal Document Mixin Methods"
 

l10n_br_fiscal/models/document_mixin.py

@@ -16,6 +16,32 @@
 
 
 class FiscalDocumentMixin(models.AbstractModel):
+    """
+    Provides a collection of reusable methods for Brazilian fiscal document logic.
+
+    This abstract model is intended to be inherited by other models or mixins
+    that require fiscal document functionalities, such as preparing fiscal data,
+    calculating fiscal amounts, managing document series, and handling comments.
+
+    It is inherited by sale.order, purchase.order, account.move and even stock.picking
+    in separate modules. Indeed these business documents need to take care of
+    some fiscal parameters before creating Fiscal Documents. And of course,
+    Fiscal Document themselves inherit from this mixin.
+
+    Key functionalities include:
+    - Computation of various fiscal amounts based on document lines.
+    - Inverse methods for distributing header-level costs (freight, insurance)
+      to lines.
+    - Hooks for customizing data retrieval (e.g., lines, fiscal partner).
+    - Onchange helpers for common fiscal fields.
+
+    Models using this mixin are often expected to also include fields defined
+    in `l10n_br_fiscal.document.mixin` for methods like
+    `_prepare_br_fiscal_dict` and `_get_amount_fields` to function
+    correctly. Line-based calculations typically rely on an overrideable
+    `_get_amount_lines` method.
+    """
+
     _name = "l10n_br_fiscal.document.mixin"
     _inherit = "l10n_br_fiscal.document.mixin.methods"
     _description = "Document Fiscal Mixin Fields"

l10n_br_fiscal/models/document_mixin_methods.py

@@ -1,7 +1,7 @@
 # Copyright (C) 2019  Renato Lima - Akretion <renato.lima@akretion.com.br>
 # License AGPL-3 - See http://www.gnu.org/licenses/agpl-3.0.html
 
-from odoo import api, models
+from odoo import Command, api, models
 
 from ..constants.fiscal import (
     COMMENT_TYPE_COMMERCIAL,
@@ -11,6 +11,28 @@
 
 
 class FiscalDocumentMixinMethods(models.AbstractModel):
+    """
+    Provides the method implementations for l10n_br_fiscal.document.mixin.
+
+    These methods are extracted into this separate mixin due to the way
+    l10n_br_fiscal.document.line is incorporated into account.move
+    by the l10n_br_account module (decorator pattern).
+
+    Specifically:
+    - In l10n_br_account, fields from l10n_br_fiscal.document
+      are added to account.move using Odoo's `_inherits` (composition)
+      mechanism.
+    - The methods in *this* mixin, however, are intended to be inherited
+      using the standard `_inherit` mechanism.
+
+    This separation is crucial because `_inherits` handles field composition
+    but does not inherit methods. Thus, `_inherit` is used to bring in
+    these methods. If these methods were defined in the same class as the
+    fields of l10n_br_fiscal.document.mixin (which are subject to
+    `_inherits`), and account.move.line also used `_inherit` on that
+    single class, the fields would be duplicated.
+    """
+
     _name = "l10n_br_fiscal.document.mixin.methods"
     _description = "Fiscal Document Mixin Methods"
 
@@ -64,7 +86,16 @@ def _onchange_fiscal_operation_id(self):
             self.document_subsequent_ids = subsequent_documents
 
     def _get_amount_lines(self):
-        """Get object lines instaces used to compute fields"""
+        """
+        Hook method to retrieve the document lines used for amount calculations.
+
+        This method should be overridden by models that inherit this mixin
+        if their fiscal document lines are stored in a field other than
+        `fiscal_line_ids`. The returned recordset should contain line objects
+        that have the fiscal amount fields to be summed.
+
+        :return: A recordset of fiscal document line objects.
+        """
         return self.mapped("fiscal_line_ids")
 
     def _get_product_amount_lines(self):
@@ -98,6 +129,17 @@ def _compute_document_serie_id(self):
                 doc.document_serie_id = False
 
     def _compute_fiscal_amount(self):
+        """
+        Compute and sum various fiscal amounts from the document lines.
+
+        This method iterates over fields prefixed with 'amount_' (as determined
+        by `_get_amount_fields`) and sums corresponding values from the lines
+        retrieved by `_get_amount_lines`.
+
+        It handles cases where delivery costs (freight, insurance, other) are
+        defined at the document total level rather than per line.
+        """
+
         fields = self._get_amount_fields()
         for doc in self:
             values = {key: 0.0 for key in fields}
@@ -151,12 +193,17 @@ def _document_comment(self):
 
     def _get_fiscal_partner(self):
         """
-        Meant to be overriden when the l10n_br_fiscal.document partner_id should not
-        be the same as the sale.order, purchase.order, account.move (...) partner_id.
+        Hook method to determine the fiscal partner for the document.
 
-        (In the case of invoicing, the invoicing partner set by the user should
-        get priority over any invoicing contact returned by address_get.)
+        This method is designed to be overridden in implementing models if the
+        partner relevant for fiscal purposes (e.g., for tax calculations,
+        final consumer status) is different from the main `partner_id`
+        of the document record. For instance, an invoice might use a specific
+        invoicing contact derived from the main partner.
+
+        :return: A `res.partner` recordset representing the fiscal partner.
         """
+
         self.ensure_one()
         return self.partner_id