refactor: add initial comments back, add type hint to database parameter

Author: davidbm04

dynamic_db_router/router.py

@@ -32,9 +32,43 @@ def allow_migrate(self, *args, **kwargs):
 
 class in_database:
     """
-    A context manager and decorator for setting a specific database for the duration of a block of code.
+    A decorator and context manager to do queries on a given database.
+    :type database: str or dict
+    :param database: The database to run queries on. A string
+        will route through the matching database in
+        ``django.conf.settings.DATABASES``. A dictionary will set up a
+        connection with the given configuration and route queries to it.
+    :type read: bool, optional
+    :param read: Controls whether database reads will route through
+        the provided database. If ``False``, reads will route through
+        the ``'default'`` database. Defaults to ``True``.
+    :type write: bool, optional
+    :param write: Controls whether database writes will route to
+        the provided database. If ``False``, writes will route to
+        the ``'default'`` database. Defaults to ``False``.
+    When used as eithe a decorator or a context manager, `in_database`
+    requires a single argument, which is the name of the database to
+    route queries to, or a configuration dictionary for a database to
+    route to.
+    Usage as a context manager:
+    .. code-block:: python
+        from my_django_app.utils import tricky_query
+        with in_database('Database_A'):
+            results = tricky_query()
+    Usage as a decorator:
+    .. code-block:: python
+        from my_django_app.models import Account
+        @in_database('Database_B')
+        def lowest_id_account():
+            Account.objects.order_by('-id')[0]
+    Used with a configuration dictionary:
+    .. code-block:: python
+        db_config = {'ENGINE': 'django.db.backends.sqlite3',
+                     'NAME': 'path/to/mydatabase.db'}
+        with in_database(db_config):
+            # Run queries
     """
-    def __init__(self, database, read=True, write=False):
+    def __init__(self, database: str | dict, read=True, write=False):
         self.read = read
         self.write = write
         self.database = database