improved docstring adder

src/quemb/shared/helpers.py

@@ -0,0 +1,35 @@
+from typing import Callable, TypeVar
+
+Function = TypeVar("Function", bound=Callable)
+
+
+# Note that we have once Callable and once Function.
+# This is **intentional**.
+# The inner function `update_doc` takes a function
+# and returns a function **with** the exact same signature.
+def add_docstring(doc: str) -> Callable[[Function], Function]:
+    """Add a docstring to a function.
+
+    Is useful for programmatically generating docstrings.
+
+    Parameters
+    ----------
+    doc: str
+        A docstring.
+
+    Example
+    ----------
+    >>> @add_docstring("Returns 'asdf'")
+    >>> def f():
+    >>>     return 'asdf'
+    is equivalent to
+    >>> def f():
+    >>>     "Returns 'asdf'"
+    >>>     return 'asdf'
+    """
+
+    def update_doc(f: Function) -> Function:
+        f.__doc__ = doc
+        return f
+
+    return update_doc