From 8f54386aab23abd621c2e706a79704ed96954178 Mon Sep 17 00:00:00 2001
From: Florent Kermarrec <florent@enjoy-digital.fr>
Date: Thu, 24 Aug 2023 09:10:55 +0200
Subject: [PATCH] gen/fhdl/module: Add some comments.

---
 litex/gen/fhdl/module.py | 45 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 41 insertions(+), 4 deletions(-)

diff --git a/litex/gen/fhdl/module.py b/litex/gen/fhdl/module.py
index fe756318e7..8a389cbe8a 100644
--- a/litex/gen/fhdl/module.py
+++ b/litex/gen/fhdl/module.py
@@ -1,7 +1,7 @@
 #
 # This file is part of LiteX.
 #
-# This file is Copyright (c) 2022 Florent Kermarrec <florent@enjoy-digital.fr>
+# This file is Copyright (c) 2022-2023 Florent Kermarrec <florent@enjoy-digital.fr>
 # SPDX-License-Identifier: BSD-2-Clause
 
 from migen import *
@@ -14,12 +14,23 @@
 # LiteX Module -------------------------------------------------------------------------------------
 
 class LiteXModule(Module, AutoCSR, AutoDoc):
+    """
+    LiteXModule is an enhancement of the Migen Module, offering additional features and simplifications
+    for users to handle submodules, specials, and clock domains. It is integrated with AutoCSR and
+    AutoDoc for CSR and documentation automation, respectively.
+    """
+
     def __setattr__(m, name, value):
-        # Migen:
+        """
+        Overrides the default behavior of attribute assignment in Python. This method simplifies the
+        process of adding submodules, specials, and clock domains in LiteX compared to Migen.
+        """
+
+        # Migen behavior:
         if name in ["comb", "sync", "specials", "submodules", "clock_domains"]:
             if not isinstance(value, _ModuleProxy):
                 raise AttributeError("Attempted to assign special Module property - use += instead")
-        # LiteX fix-up: Automatically collect specials/submodules/clock_domains:
+        # Automatic handling for adding submodules, specials, and clock domains in LiteX.
         # - m.module_x  = .. equivalent of Migen's m.submodules.module_x = ..
         # Note: Do an exception for CSRs that have a specific collection mechanism.
         elif (isinstance(value, Module)      and ((name, value) not in m._submodules) and (not isinstance(value, _CSRBase))):
@@ -34,8 +45,12 @@ def __setattr__(m, name, value):
         else:
             object.__setattr__(m, name, value)
 
-    # LiteX fix-up: Automatically collect specials/submodules/clock_domains:
     def __iadd__(m, other):
+        """
+        Overrides the default behavior of "+=" in Python. Simplifies addition of submodules, specials,
+        and clock domains.
+        """
+
         # - m += module_x  equivalent of Migen's m.submodules += module_x.
         if isinstance(other, Module):
             print(other)
@@ -52,11 +67,33 @@ def __iadd__(m, other):
         return m
 
     def add_module(self, name, module):
+        """
+        Add a submodule to the current module.
+
+        Args:
+            name (str): Name to assign to the submodule.
+            module (Module): Submodule to be added.
+
+        Raises:
+            AssertionError: If provided object is not a Module or module name already exists.
+        """
         assert isinstance(module, Module)
         assert not hasattr(self, name)
         setattr(self, name, module)
 
     def get_module(self, name):
+        """
+        Retrieve a submodule by its name.
+
+        Args:
+            name (str): Name of the submodule to retrieve.
+
+        Returns:
+            module (Module or None): Returns the module if found, otherwise None.
+
+        Raises:
+            AssertionError: If found object is not of type Module.
+        """
         module = getattr(self, name, None)
         if module is not None:
             assert isinstance(module, Module)