Improve documentation.v0.2.1

1 files changed, 23 insertions, 1 deletions

diff --git a/rainbow_parenthesis/__init__.py b/rainbow_parenthesis/__init__.py
index e665bdb..c029b3f 100644
--- a/rainbow_parenthesis/__init__.py
+++ b/rainbow_parenthesis/__init__.py
@@ -60,7 +60,29 @@ def color(depth: int, c: str) -> Colored:
 
 def colorize(strm: io.TextIOBase) -> Generator[str | Colored, None, None]:
     """
-    Colorize a given string.
+    Color all parenthesis in the given stream.
+
+    Each character in the stream is checked if it's a either a
+    parenthesis, square bracket, or curly bracket, and if so, a
+    `Colored` token is returned.
+
+    If a single or double qutation mark is encountered, then "string
+    mode" is entered, in which parentheses are treated like any other
+    character (e.g. not highlighted). String mode continues until the
+    corresponding token is found.
+
+    If a token is preceeded by a backslash, then first the backslash
+    is yielded, followed by the token as a raw character.
+
+    .. code-block:: python
+       :caption:
+         Example usage with a string as input
+
+       >>> import io
+       >>> list(colorize(io.StringIO"(Hello)")))
+        [ Colored(depth=0, item='('),
+          'H', 'e', 'l', 'l', 'o',
+          Colored(depth=0, item=')') ]
 
     :param strm:
         Text stream to get contents from.