add some documentation for heap sort (#9949)

* add some documentation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix typing

* Update heap_sort.py

* Update heap_sort.py

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Christian Clauss <[email protected]>

sorts/heap_sort.py

@@ -1,17 +1,22 @@
 """
-This is a pure Python implementation of the heap sort algorithm.
-
-For doctests run following command:
-python -m doctest -v heap_sort.py
-or
-python3 -m doctest -v heap_sort.py
-
-For manual testing run:
-python heap_sort.py
+A pure Python implementation of the heap sort algorithm.
 """
 
 
-def heapify(unsorted, index, heap_size):
+def heapify(unsorted: list[int], index: int, heap_size: int) -> None:
+    """
+    :param unsorted: unsorted list containing integers numbers
+    :param index: index
+    :param heap_size: size of the heap
+    :return: None
+    >>> unsorted = [1, 4, 3, 5, 2]
+    >>> heapify(unsorted, 0, len(unsorted))
+    >>> unsorted
+    [4, 5, 3, 1, 2]
+    >>> heapify(unsorted, 0, len(unsorted))
+    >>> unsorted
+    [5, 4, 3, 1, 2]
+    """
     largest = index
     left_index = 2 * index + 1
     right_index = 2 * index + 2
@@ -22,26 +27,26 @@ def heapify(unsorted, index, heap_size):
         largest = right_index
 
     if largest != index:
-        unsorted[largest], unsorted[index] = unsorted[index], unsorted[largest]
+        unsorted[largest], unsorted[index] = (unsorted[index], unsorted[largest])
         heapify(unsorted, largest, heap_size)
 
 
-def heap_sort(unsorted):
+def heap_sort(unsorted: list[int]) -> list[int]:
     """
-    Pure implementation of the heap sort algorithm in Python
-    :param collection: some mutable ordered collection with heterogeneous
-    comparable items inside
+    A pure Python implementation of the heap sort algorithm
+
+    :param collection: a mutable ordered collection of heterogeneous comparable items
     :return: the same collection ordered by ascending
 
     Examples:
     >>> heap_sort([0, 5, 3, 2, 2])
     [0, 2, 2, 3, 5]
-
     >>> heap_sort([])
     []
-
     >>> heap_sort([-2, -5, -45])
     [-45, -5, -2]
+    >>> heap_sort([3, 7, 9, 28, 123, -5, 8, -30, -200, 0, 4])
+    [-200, -30, -5, 0, 3, 4, 7, 8, 9, 28, 123]
     """
     n = len(unsorted)
     for i in range(n // 2 - 1, -1, -1):
@@ -53,6 +58,10 @@ def heap_sort(unsorted):
 
 
 if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()
     user_input = input("Enter numbers separated by a comma:\n").strip()
-    unsorted = [int(item) for item in user_input.split(",")]
-    print(heap_sort(unsorted))
+    if user_input:
+        unsorted = [int(item) for item in user_input.split(",")]
+        print(f"{heap_sort(unsorted) = }")