docs: add missing docstrings to tim_sort helpers

Add docstrings with doctests to binary_search, insertion_sort,
merge, and main in sorts/tim_sort.py, making helpers consistent
with the already-documented tim_sort.

Fixes #14773

Author: deepshekhardas

sorts/tim_sort.py

@@ -2,6 +2,18 @@
 
 
 def binary_search(lst: list[Any], item: Any, start: int, end: int) -> int:
+    """Return the insertion index for item in sorted lst[start:end+1].
+
+    Uses binary search to find where item should be inserted to keep
+    the sublist sorted. Used by insertion_sort.
+
+    >>> binary_search([1, 3, 5, 7], 4, 0, 3)
+    2
+    >>> binary_search([1, 3, 5, 7], 0, 0, 3)
+    0
+    >>> binary_search([1, 3, 5, 7], 8, 0, 3)
+    4
+    """
     if start == end:
         return start if lst[start] > item else start + 1
     if start > end:
@@ -17,6 +29,15 @@ def binary_search(lst: list[Any], item: Any, start: int, end: int) -> int:
 
 
 def insertion_sort(lst: list[Any]) -> list[Any]:
+    """Sort lst using insertion sort with binary_search for position.
+
+    >>> insertion_sort([3, 1, 2])
+    [1, 2, 3]
+    >>> insertion_sort([5, 9, 10, 3, -4])
+    [-4, 3, 5, 9, 10]
+    >>> insertion_sort([])
+    []
+    """
     length = len(lst)
 
     for index in range(1, length):
@@ -28,6 +49,15 @@ def insertion_sort(lst: list[Any]) -> list[Any]:
 
 
 def merge(left: list[Any], right: list[Any]) -> list[Any]:
+    """Merge two sorted lists into a single sorted list.
+
+    >>> merge([1, 3, 5], [2, 4, 6])
+    [1, 2, 3, 4, 5, 6]
+    >>> merge([], [1, 2])
+    [1, 2]
+    >>> merge([1, 2], [])
+    [1, 2]
+    """
     if not left:
         return right
 
@@ -76,6 +106,7 @@ def tim_sort(lst: list[Any] | tuple[Any, ...] | str) -> list[Any]:
 
 
 def main():
+    """Demonstrate tim_sort on a sample list."""
     lst = [5, 9, 10, 3, -4, 5, 178, 92, 46, -18, 0, 7]
     sorted_lst = tim_sort(lst)
     print(sorted_lst)