From da55d88ddf4a302eb2d76b6d2243b8f87ff2e661 Mon Sep 17 00:00:00 2001
From: JOLIMAITRE Matthieu <matthieu@imagevo.fr>
Date: Tue, 21 May 2024 03:48:55 +0200
Subject: [PATCH] add doc comments

---
 pyproject.toml   |  2 +-
 src/okipy/lib.py | 62 ++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 61 insertions(+), 3 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 3c33281..8182635 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,7 +1,7 @@
 
 [project]
 name = "okipy"
-version = "1.0.1"
+version = "1.1.0"
 description = "Minimal, typed, functional and dynamic test library."
 keywords = ["test", "functional", "library", "testing", "dynamic", "minimal"]
 
diff --git a/src/okipy/lib.py b/src/okipy/lib.py
index 889849f..c8a74fd 100644
--- a/src/okipy/lib.py
+++ b/src/okipy/lib.py
@@ -17,6 +17,16 @@ class Ctx:
 
     @contextmanager
     def assert_raises(self, except_kind: type[BaseException] = BaseException):
+        """
+        Asserts that a section of code will raise an exception.
+        ```py
+        @test()
+        def it_works(ctx):
+            a = 1
+            with ctx.assert_raises():
+                assert a + 1 == 3
+        ```
+        """
         try:
             yield
         except except_kind as exc:
@@ -50,14 +60,25 @@ class TestFailure:
 
 
 class Test:
+    """
+    Represents one test to run.
+    """
     name: str
     procedure: Callable[[Ctx], Any]
 
     def __init__(self, name: str, procedure: Callable[[Ctx], Any]) -> None:
+        """
+        Takes the name of the test and the test content procedure.
+        """
         self.name = name
         self.procedure = procedure
 
     def run(self):
+        """
+        Runs this test infallibly.
+
+        Returns a `TestFailure` if the test failed or `None` if it succeeded.
+        """
         with CaptureOutput() as capture:
             try:
                 self.procedure(Ctx(self))
@@ -69,7 +90,7 @@ class Suite:
     """
     A suite of tests.
     
-    Append test with the `Suite.test` decorator :
+    Append test with the `Suite.test` decorator.
     ```py
     suite = Suite("Feur")
 
@@ -83,11 +104,28 @@ class Suite:
     name: Union[str, None]
     tests: list[Test]
 
-    def __init__(self, name: Union[str, None] = None) -> None:
+    def __init__(self, name: Optional[str] = None) -> None:
+        """
+        Creates an empty test suite.
+
+        Naming is optionnal.
+        """
         self.name = name
         self.tests = []
 
     def test(self):
+        """
+        Decorator used to append a function into the suite as a test.
+        ```py
+        suite = Suite("Feur")
+
+        @suite.test()
+        def it_works(ctx):
+            assert 1 + 1 == 2
+
+        suite.run()
+        ```
+        """
         def decorate(procedure: Callable[[Ctx], Any]) -> Callable[[Ctx], Any]:
             name = procedure.__name__
             self.tests.append(Test(name, procedure))
@@ -95,6 +133,11 @@ class Suite:
         return decorate
 
     def run(self, filters: list[str] = []):
+        """
+        Runs the test suite.
+
+        Optionnally filter to run by their name : Only keep tests which names contains all filters.
+        """
         if self.name is not None:
             print(" ", green("Suite"), bold(self.name))
         to_run = [*self.filter_tests(filters)]
@@ -125,6 +168,11 @@ class Suite:
 
 
 def get_inline_suite() -> Suite:
+    """
+    Accessor of a singleton the `Suite` containing all inline tests.
+
+    Intended for internal use only.
+    """
     existing: Optional[Suite] = globals().get('_okipy_inline_suite')
     if existing is None:
         globals()['_okipy_inline_suite'] = existing = Suite()
@@ -132,6 +180,16 @@ def get_inline_suite() -> Suite:
 
 
 def test():
+    """
+    Decorator for declaring inline tests.
+    ```py
+    @test()
+    def it_works(ctx):
+        a = 1
+        with ctx.assert_raises():
+            assert a + 1 == 3
+    ```
+    """
     def decorate(procedure: Callable[[Ctx], Any]) -> Callable[[Ctx], Any]:
         return get_inline_suite().test()(procedure)
     return decorate