Update api-docs.txt

Author: rich-iannone

pointblank/data/api-docs.txt

@@ -708,8 +708,9 @@ FinalActions(*args)
     In this example, the `send_alert()` function is defined to check the validation summary for
     critical failures. If any are found, an alert message is printed to the console. The function is
     passed to the `FinalActions` class, which ensures it will be executed after all validation steps
-    are complete. Note that we used the `get_validation_summary()` function to retrieve the summary
-    of the validation results to help craft the alert message.
+    are complete. Note that we used the
+    [`get_validation_summary()`](`pointblank.get_validation_summary`) function to retrieve the
+    summary of the validation results to help craft the alert message.
 
     Multiple final actions can be provided in a sequence. They will be executed in the order they
     are specified after all validation steps have completed:
@@ -5208,13 +5209,11 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
         ----------
         expr
             A callable function that defines the specialized validation logic. This function should:
-
-            - accept the target data table as its single argument (though it may ignore it), or
-            - take no parameters at all (for environment validations)
-
-            The function must ultimately return boolean values representing validation results.
-            Design your function to incorporate any custom parameters directly within the function
-            itself using closure variables or default parameters.
+            (1) accept the target data table as its single argument (though it may ignore it), or
+            (2) take no parameters at all (for environment validations). The function must
+            ultimately return boolean values representing validation results. Design your function
+            to incorporate any custom parameters directly within the function itself using closure
+            variables or default parameters.
         pre
             An optional preprocessing function or lambda to apply to the data table during
             interrogation. This function should take a table as input and return a modified table.
@@ -5302,7 +5301,7 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
         import pointblank as pb
         import polars as pl
 
-        tbl = pl.DataFrame({
+        simple_tbl = pl.DataFrame({
             "a": [5, 7, 1, 3, 9, 4],
             "b": [6, 3, 0, 5, 8, 2]
         })
@@ -5312,7 +5311,7 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
             return data.select(pl.col("a") + pl.col("b") > 0)
 
         (
-            pb.Validate(data=tbl)
+            pb.Validate(data=simple_tbl)
             .specially(expr=validate_sum_positive)
             .interrogate()
         )
@@ -5336,7 +5335,7 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
             return validate_column_ratio
 
         (
-            pb.Validate(data=tbl)
+            pb.Validate(data=simple_tbl)
             .specially(
                 expr=make_column_ratio_validator(col1="a", col2="b", min_ratio=0.5)
             )
@@ -5358,7 +5357,7 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
         import random
 
         # Create sample data
-        tbl = pl.DataFrame({
+        transaction_tbl = pl.DataFrame({
             "transaction_id": [f"TX{i:04d}" for i in range(1, 11)],
             "amount": [120.50, 85.25, 50.00, 240.75, 35.20, 150.00, 85.25, 65.00, 210.75, 90.50],
             "category": ["food", "shopping", "entertainment", "travel", "utilities",
@@ -5390,7 +5389,7 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
             return test_results
 
         (
-            pb.Validate(data=tbl)
+            pb.Validate(data=transaction_tbl)
             .specially(
                 expr=validate_transaction_rules,
                 brief="Validate transaction IDs and amounts by category."
@@ -5401,13 +5400,12 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
 
         This example shows how to create a validation function that applies multiple business rules
         to each row and returns a list of boolean results. Each boolean in the list represents a
-        separate test unit (one per row), and the validation passes only if all rules are satisfied
-        for a given row.
+        separate test unit, and a test unit passes only if all rules are satisfied for a given row.
 
         The function iterates through each row in the data table, checking:
 
-        1. If transaction IDs follow the required format
-        2. If transaction amounts are appropriate for their respective categories
+        1. if transaction IDs follow the required format
+        2. if transaction amounts are appropriate for their respective categories
 
         This approach is powerful when you need to apply complex, conditional logic that can't be
         easily expressed using the built-in validation functions.
@@ -5429,7 +5427,7 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
             return has_large_values and has_positive_mean
 
         (
-            pb.Validate(data=tbl)
+            pb.Validate(data=simple_tbl)
             .specially(expr=validate_table_properties)
             .interrogate()
         )
@@ -5440,8 +5438,8 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
 
         ### Environment validation that doesn't use the data table
 
-        The `specially()` method can even be used to validate aspects of your environment that are
-        completely independent of the data:
+        The `specially()` validation method can even be used to validate aspects of your environment
+        that are completely independent of the data:
 
         ```python
         def validate_pointblank_version():
@@ -5463,7 +5461,7 @@ specially(self, expr: 'Callable', pre: 'Callable | None' = None, thresholds: 'in
                 return False
 
         (
-            pb.Validate(data=tbl)
+            pb.Validate(data=simple_tbl)
             .specially(
                 expr=validate_pointblank_version,
                 brief="Check Pointblank version `>=0.9.0`."
@@ -9463,7 +9461,7 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
     validation
     ```
 
-    By placing the `notify_slack` function in the `Validate(actions=Actions(critical=))` argument,
+    By placing the `notify_slack()` function in the `Validate(actions=Actions(critical=))` argument,
     you can ensure that the notification is sent whenever the 'critical' threshold is reached (as
     set here, when 15% or more of the test units fail). The notification will include information
     about the validation step that triggered the alert.
@@ -9493,7 +9491,7 @@ send_slack_notification(webhook_url: 'str | None' = None, step_msg: 'str | None'
     )
     ```
 
-    In this case, the same `notify_slack` function is used, but it is placed in
+    In this case, the same `notify_slack()` function is used, but it is placed in
     `Validate(final_actions=FinalActions())`. This results in the summary notification being sent
     after all validation steps are completed, regardless of whether any steps failed or not.