Added a docstring to chain_functions.

4 files changed, 44 insertions, 1 deletions

diff --git a/docs/source/api.rst b/docs/source/api.rst
index 48728ee..76a2520 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -21,3 +21,4 @@ natsort API
    order_by_index.rst
    ns_class.rst
    bytes.rst
+   chain.rst
diff --git a/docs/source/chain.rst b/docs/source/chain.rst
new file mode 100644
index 0000000..5f59706
--- /dev/null
+++ b/docs/source/chain.rst
@@ -0,0 +1,16 @@
+.. default-domain:: py
+.. currentmodule:: natsort
+
+.. _function_help:
+
+Help With Creating Function Keys
+================================
+
+If you need to create a complicated *key* argument to (for example)
+:func:`natsorted` that is actually multiple functions called one after the other,
+the following function can help you easily perform this action. It is
+used internally to :mod:`natsort`, and has been exposed publically for
+the convenience of the user.
+
+.. autofunction:: chain_functions
+
diff --git a/natsort/__init__.py b/natsort/__init__.py
index 2e48601..edb435f 100644
--- a/natsort/__init__.py
+++ b/natsort/__init__.py
@@ -24,6 +24,7 @@ from natsort.natsort import (
     as_utf8,
     ns,
 )
+from natsort.utils import chain_functions
 from natsort._version import __version__
 
 __all__ = [
@@ -42,4 +43,5 @@ __all__ = [
     'as_ascii',
     'as_utf8',
     'ns',
+    'chain_functions',
 ]
diff --git a/natsort/utils.py b/natsort/utils.py
index 6bffdf9..527b3e0 100644
--- a/natsort/utils.py
+++ b/natsort/utils.py
@@ -350,7 +350,31 @@ def _post_string_parse_function(alg, sep):
 
 
 def chain_functions(functions):
-    """Chain a list of single-argument functions together and return"""
+    """
+    Chain a list of single-argument functions together and return.
+
+    The functions are applied in list order, and the output of the
+    previous functions is passed to the next function.
+
+    Parameters
+    ----------
+    functions : list
+        A list of single-argument functions to chain together.
+
+    Returns
+    -------
+    A single argument function.
+
+    Examples
+    --------
+    Chain several functions together!
+
+        >>> funcs = [lambda x: x * 4, len, lambda x: x + 5]
+        >>> func = chain_functions(funcs)
+        >>> func('hey')
+        17
+
+    """
     def func(x, _functions=functions):
         output = x
         for f in _functions: