add some global documentation for leancheck.py

src/leancheck.py

@@ -4,6 +4,44 @@
 #
 # (C) 2023-2024  Rudy Matela
 # Distributed under the LGPL v2.1 or later (see the file LICENSE)
+"""
+This is a port of [Haskell's LeanCheck] to [Python].
+
+[Haskell's LeanCheck]: https://hackage.haskell.org/package/leancheck
+[Python]: https://python.org
+
+LeanCheck is an enumerative property-based testing library.
+It can be used to complement your unit tests.
+
+The usual drill in unit testing involves making assertions
+about specific input-output cases of functions, such as:
+
+    assertEqual(sorted([4,2,1,3]), [1,2,3,4])
+
+There are no arguments to the unit test.
+
+In property-based testing (with LeanCheck)
+one writes more general properties that should be true
+for a given set of arguments.
+
+For example:
+given __any__ list, sorting it twice is the same as sorting it once.
+We can encode this as a function returning a boolean value:
+
+    >>> def prop_sorted_twice(xs: list[int]) -> bool:
+    ...     return sorted(sorted(xs)) == sorted(xs)
+
+For whatever list we provide this function,
+it should return `True`.
+Now one can use LeanCheck to verify this automatically:
+
+    >>> check(prop_sorted_twice)
+    +++ OK, passed 360 tests: prop_sorted_twice
+    True
+
+LeanCheck automatically came up with 360 unique lists
+to exercise the property.
+"""
 
 
 import inspect