From 53d223445bab86c46c13ddabedb13977a4384729 Mon Sep 17 00:00:00 2001
From: Philipp Temminghoff <philipptemminghoff@googlemail.com>
Date: Mon, 4 Nov 2024 19:46:40 +0100
Subject: [PATCH] chore: docstrings

---
 src/jinjarope/deepmerge.py | 82 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 78 insertions(+), 4 deletions(-)

diff --git a/src/jinjarope/deepmerge.py b/src/jinjarope/deepmerge.py
index 92560c1..26c9ac1 100644
--- a/src/jinjarope/deepmerge.py
+++ b/src/jinjarope/deepmerge.py
@@ -1,3 +1,5 @@
+"""Module for deep merging of data structures with customizable merge strategies."""
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, TypeVar
@@ -11,19 +13,55 @@
 
 
 def merge_dict(merger: DeepMerger, source: Mapping, target: Mapping) -> Mapping:
+    """Merge two mappings recursively.
+
+    Args:
+        merger: The DeepMerger instance handling the merge operation
+        source: The source mapping whose values take precedence
+        target: The target mapping to merge into
+
+    Returns:
+        A new dictionary containing the merged key-value pairs
+
+    Example:
+        ```python
+        merger = DeepMerger()
+        source = {"a": {"b": 1}}
+        target = {"a": {"c": 2}}
+        merge_dict(merger, source, target)
+        # {'a': {'b': 1, 'c': 2}}
+        ```
+    """
     result = dict(target)
     for key, source_value in source.items():
-        target_value = result[key] if key in result else type(source_value)()
+        target_value = result.get(key, type(source_value)())
         try:
             value = merger.merge(source_value, target_value)
         except TypeError:
-            # can't merge, so overwrite
+            # If values can't be merged, use source value
             value = source_value
         result[key] = value
     return result
 
 
 def merge_list(merger: DeepMerger, source: list, target: list) -> list:
+    """Concatenate two lists.
+
+    Args:
+        merger: The DeepMerger instance handling the merge operation
+        source: The source list to append
+        target: The target list to merge into
+
+    Returns:
+        A new list containing all elements from both lists
+
+    Example:
+        ```python
+        merger = DeepMerger()
+        merge_list(merger, [3, 4], [1, 2])
+        # [1, 2, 3, 4]
+        ```
+    """
     return target + source
 
 
@@ -34,13 +72,49 @@ def merge_list(merger: DeepMerger, source: list, target: list) -> list:
 
 
 class DeepMerger:
-    mergers = DEFAULT_MERGERS
+    """A class that handles deep merging of data structures.
+
+    The merger can be customized by providing different merge strategies for different types.
+
+    Attributes:
+        mergers: A dictionary mapping types to their corresponding merge functions
+
+    Example:
+        ```python
+        merger = DeepMerger()
+        source = {"a": {"b": 1}}
+        target = {"a": {"c": 2}}
+        merger.merge(source, target)
+        # {'a': {'b': 1, 'c': 2}}
+        ```
+    """
+
+    mergers: dict[type[Any], Callable[..., Any]] = DEFAULT_MERGERS
 
-    def __init__(self, mergers: dict[type, Callable] | None = None):
+    def __init__(
+        self, mergers: dict[type[Any], Callable[..., Any]] | None = None
+    ) -> None:
+        """Initialize the DeepMerger with custom merge strategies.
+
+        Args:
+            mergers: Optional dictionary of type-specific merge functions
+        """
         if mergers is not None:
             self.mergers = mergers
 
     def merge(self, source: T, target: T) -> T:
+        """Merge two objects of the same type.
+
+        Args:
+            source: The source object whose values take precedence
+            target: The target object to merge into
+
+        Returns:
+            The merged object
+
+        Raises:
+            TypeError: If the types cannot be merged
+        """
         source_type = type(source)
         target_type = type(target)
         merger = self.mergers.get(target_type)