docs: deprecation of dispatch(..., pre_call=...)

This is not in fact deprecation per se but merely an attempt to draw
attention to a fact that was mentioned almost ten years ago in the
discussion (#63): the `pre_call` argument in `dispatch()` is not a
feature but a hack which is not recommended and will be removed.

This commit makes it clear when precisely it is going to be removed and
what actions are expected from the user.

CHANGES

@@ -21,6 +21,16 @@ Deprecated features, to be removed in v.0.30:
 
   - Not relevant anymore.  Please use the built-in `input()` instead.
 
+- argument `pre_call` in `dispatch()`.
+
+   Even though this hack seems to have been used in some projects, it was never
+   part of the official API and never recommended.
+
+   Describing your use case in the `discussion about shared arguments`_ can
+   help improve the library to accomodate it in a proper way.
+
+   .. _discussion about shared arguments: https://github.com/neithere/argh/issues/63
+
 - Argument help as annotations.
 
   - Annotations will only be used for types after v.0.30.

src/argh/dispatching.py

@@ -223,10 +223,18 @@ def _execute_command(function, namespace_obj, errors_file, pre_call=None):
     All other exceptions propagate unless marked as wrappable
     by :func:`wrap_errors`.
     """
-    if pre_call:  # XXX undocumented because I'm unsure if it's OK
-        # Actually used in real projects:
-        # * https://google.com/search?q=argh+dispatch+pre_call
-        # * https://github.com/neithere/argh/issues/63
+    # TODO: remove in v.0.30
+    if pre_call:  # pragma: no cover
+        # This is NOT a documented and recommended API.
+        # The common use case for this hack is to inject shared arguments.
+        # Such approach would promote an approach which is not in line with the
+        # purpose of the library, i.e. to keep things natural and "pythonic".
+        # Argh is about keeping CLI in line with function signatures.
+        # The `pre_call` hack effectively destroys this mapping.
+        # There should be a better solution, e.g. decorators and/or some shared
+        # objects.
+        #
+        # See discussion here: https://github.com/neithere/argh/issues/63
         pre_call(namespace_obj)
 
     # the function is nested to catch certain exceptions (see below)