Polish docstrings

.github/CONTRIBUTING.md

@@ -75,15 +75,20 @@ You will find the built documentation in `docs/_build/html`.
   We use the `"""`-on-separate-lines style for docstrings with [Napoleon]-style API documentation:
 
   ```python
-  def func(x: str) -> str:
+  def func(x: str, y: int) -> str:
       """
       Do something.
 
-      Parameters:
-        x: A very important parameter.
+      Arguments:
+          x: A very important argument.
+
+          y:
+            Another very important argument, but its description is so long
+            that it doesn't fit on one line. So we start the whole block on a
+            fresh new line to keep the block together.
 
       Returns:
-        The result of doing something.
+          The result of doing something.
       """
   ```
 

src/svcs/_core.py

@@ -137,8 +137,8 @@ class Registry:
 
     Warns:
 
-        ResourceWarning: If a registry with pending cleanups is
-            garbage-collected.
+        ResourceWarning:
+            If a registry with pending cleanups is garbage-collected.
     """
 
     _services: dict[type, RegisteredService] = attrs.Factory(dict)
@@ -211,32 +211,36 @@ def register_factory(
         *on_registry_close* callbacks are run all together when the registry is
         closed.
 
-        Args:
+        Arguments:
             svc_type: The type of the service to register.
 
-            factory: A callable that is used to instantiated *svc_type* if
-                asked. If it's a generator or a context manager, a cleanup is
-                registered after instantiation.
+            factory:
+                A callable that is used to instantiated *svc_type* if asked. If
+                it's a generator or a context manager, a cleanup is registered
+                after instantiation.
 
-                Can also be an async callable/generator/context manager..
+                Can also be an async callable/generator/context manager.
 
                 If *factory* takes a first argument called ``svcs_container``
                 or the first argument (of any name) is annotated as being
                 :class:`svcs.Container`, the container instance that is
                 instantiating the service is passed into the factory as the
                 first positional argument.
 
-            enter: Whether to enter context managers if one is returned by
+            enter:
+                Whether to enter context managers if one is returned by
                  *factory*. Usually you want that, but there are occasions --
                  like database transaction managers -- that you want to enter
                  manually.
 
-            ping: A callable that marks the service as having a health check.
+            ping:
+                A callable that marks the service as having a health check.
 
                 .. seealso::
                     :meth:`Container.get_pings` and :class:`ServicePing`.
 
-            on_registry_close: A callable that is called when the
+            on_registry_close:
+                A callable that is called when the
                 :meth:`svcs.Registry.close()` method is called.
 
                 Can also be an async callable or an
@@ -541,7 +545,6 @@ def close(self) -> None:
         Errors are logged at warning level, but otherwise ignored.
 
         .. hint::
-
             The Container can be used again after this. Closing it is an
             idempotent way to reset it.
         """
@@ -581,7 +584,6 @@ async def aclose(self) -> None:
         use this.
 
         .. hint::
-
             The Container can be used again after this. Closing it is an
             idempotent way to reset it.
         """

src/svcs/flask.py

@@ -45,8 +45,7 @@ def get_registry(app: Flask | None = None) -> Registry:
     """
     Get the registry from *app* or :obj:`flask.current_app`.
 
-    Args:
-
+    Arguments:
         app: If None, :obj:`flask.current_app` is used.
 
     .. versionadded:: 23.21.0
@@ -141,7 +140,7 @@ def overwrite_factory(
 
     Afterwards resets the instantiation cache on ``g``.
 
-    .. seealso::
+    See also:
         - :meth:`svcs.Registry.register_factory()`
         - :meth:`svcs.Container.close()`
     """
@@ -170,7 +169,7 @@ def overwrite_value(
 
     Afterwards resets the instantiation cache on ``g``.
 
-    .. seealso::
+    See also:
         - :meth:`svcs.Registry.register_factory()`
         - :meth:`svcs.Container.close()`
     """
@@ -189,7 +188,7 @@ def get_pings() -> list[ServicePing]:
     """
     See :meth:`svcs.Container.get_pings()`.
 
-    .. seealso::
+    See also:
         :ref:`flask-health`
     """
     return svcs_from(g).get_pings()

src/svcs/pyramid.py

@@ -39,7 +39,6 @@ def svcs_from(request: Request | None = None) -> svcs.Container:
     Get the current container either from *request* or from thread locals.
 
     Arguments:
-
         request: If None, thread locals are used.
     """
     if request is None:
@@ -75,16 +74,19 @@ def init(
 
     .. _Tween: https://docs.pylonsproject.org/projects/pyramid/en/main/glossary.html#term-tween
 
-    Args:
+    Arguments:
         config: Pyramid configurator object.
 
-        registry: A custom *svcs* registry to use. If None, a new one is created.
+        registry:
+            A custom *svcs* registry to use. If None, a new one is created.
 
-        tween_under: Passed unchanged to
-            :meth:`pyramid.config.Configurator.add_tween()` as *under*.
+        tween_under:
+            Passed unchanged to :meth:`pyramid.config.Configurator.add_tween()`
+            as *under*.
 
-        tween_over: Passed unchanged to
-            :meth:`pyramid.config.Configurator.add_tween()` as *over*.
+        tween_over:
+            Passed unchanged to :meth:`pyramid.config.Configurator.add_tween()`
+            as *over*.
     """
     config.registry[_KEY_REGISTRY] = registry or svcs.Registry()
 
@@ -163,7 +165,7 @@ def close_registry(rh: PyramidRegistryHaver) -> None:
 
     Ideal for :func:`atexit.register()` handlers.
 
-    Parameters:
+    Arguments:
         rh: An object that carries a :class:`pyramid.registry.Registry`.
     """
     with suppress(KeyError):