Merge pull request #2452 from moj-analytical-services/2440-add-docstr…

…ing-to-customrule

2440 add docstring to customrule

docs/api_docs/blocking.md

@@ -3,14 +3,17 @@ tags:
   - API
   - blocking
 ---
-# Documentation for`block_on`
+# Documentation for the `blocking_rule_library`
 
-::: splink.block_on
+::: splink.blocking_rule_library
     handler: python
     options:
       show_root_heading: false
       show_root_toc: false
       show_source: false
+      members_order: source
+      inherited_members: false
+      merge_init_into_class: true
 
 
 

splink/blocking_rule_library.py

@@ -0,0 +1,13 @@
+from splink.internals.blocking_rule_library import (
+    And,
+    CustomRule,
+    Not,
+    block_on,
+)
+
+__all__ = [
+    "CustomRule",
+    "And",
+    "Not",
+    "block_on",
+]

splink/internals/blocking_rule_library.py

@@ -45,6 +45,43 @@ def __init__(
         salting_partitions: int | None = None,
         arrays_to_explode: list[str] | None = None,
     ):
+        """
+        Represents a custom blocking rule using a user-defined SQL condition.  To
+        refer to the left hand side and the right hand side of the pairwise
+        record comparison, use `l` and `r` respectively, e.g.
+        `l.first_name = r.first_name and len(l.first_name) <2`.
+
+        Args:
+            blocking_rule (str): A SQL condition string representing the custom
+                blocking rule.
+            sql_dialect (str, optional): The SQL dialect of the provided blocking rule.
+                If specified, Splink will attempt to translate the rule to the
+                appropriate dialect.
+            salting_partitions (int, optional): The number of partitions to use for
+                salting. If provided, enables salting for this blocking rule.
+            arrays_to_explode (list[str], optional): A list of array column names
+                to explode before applying the blocking rule.
+
+        Examples:
+            ```python
+            from splink.blocking_rule_library import CustomRule
+
+            # Simple custom rule
+            rule_1 = CustomRule("l.postcode = r.postcode")
+
+            # Custom rule with dialect translation
+            rule_2 = CustomRule(
+                "SUBSTR(l.surname, 1, 3) = SUBSTR(r.surname, 1, 3)",
+                sql_dialect="sqlite"
+            )
+
+            # Custom rule with salting
+            rule_3 = CustomRule(
+                "l.city = r.city",
+                salting_partitions=10
+            )
+            ```
+        """
         super().__init__(
             salting_partitions=salting_partitions, arrays_to_explode=arrays_to_explode
         )