Insertion sort : type hint, docstring

sorts/insertion_sort.py

@@ -1,18 +1,21 @@
 """
-This is a pure Python implementation of the insertion sort algorithm
+A pure Python implementation of the insertion sort algorithm
+
+This algorithm sorts a collection by comparing adjacent elements.
+When it finds that order is not respected, it moves the element compared
+backward until the order is correct.  It then goes back directly to the
+element's initial position resuming forward comparison.
 
 For doctests run following command:
-python -m doctest -v insertion_sort.py
-or
 python3 -m doctest -v insertion_sort.py
 
 For manual testing run:
-python insertion_sort.py
+python3 insertion_sort.py
 """
 
 
-def insertion_sort(collection):
-    """Pure implementation of the insertion sort algorithm in Python
+def insertion_sort(collection: list) -> list:
+    """A pure Python implementation of the insertion sort algorithm
 
     :param collection: some mutable ordered collection with heterogeneous
     comparable items inside
@@ -47,4 +50,4 @@ def insertion_sort(collection):
 if __name__ == "__main__":
     user_input = input("Enter numbers separated by a comma:\n").strip()
     unsorted = [int(item) for item in user_input.split(",")]
-    print(insertion_sort(unsorted))
+    print(f"{insertion_sort(unsorted) = }")