docs: docs and docstrings.

ansible_mitogen/connection.py

@@ -487,8 +487,9 @@ class Connection(ansible.plugins.connection.ConnectionBase):
         the delegated-to machine.
 
         When running with delegate_to, Ansible tasks have variables associated
-        with the original machine, therefore it does not make sense to extract
-        connection-related configuration information from them.
+        with the original machine, not the delegated-to machine, therefore it
+        does not make sense to extract connection-related configuration for the
+        delegated-to machine from them.
         """
         if self._task_vars:
             if self.delegate_to_hostname is None:
@@ -515,7 +516,7 @@ class Connection(ansible.plugins.connection.ConnectionBase):
     def _spec_from_via(self, via_spec):
         """
         Produce a dict connection specifiction given a string `via_spec`, of
-        the form `[become_user@]inventory_hostname`.
+        the form `[[become_method:]become_user@]inventory_hostname`.
         """
         become_user, _, inventory_name = via_spec.rpartition('@')
         become_method, _, become_user = become_user.rpartition(':')
@@ -540,6 +541,33 @@ class Connection(ansible.plugins.connection.ConnectionBase):
     via_cycle_msg = 'mitogen_via=%s of %s creates a cycle (%s)'
 
     def _stack_from_spec(self, spec, stack=(), seen_names=()):
+        """
+        Return a tuple of ContextService parameter dictionaries corresponding
+        to the connection described by `spec`, and any connection referenced by
+        its `mitogen_via` or `become` fields. Each element is a dict of the
+        form::
+
+            {
+                # Optional. If present and `True`, this hop is elegible for
+                # interpreter recycling.
+                "enable_lru": True,
+                # mitogen.master.Router method name.
+                "method": "ssh",
+                # mitogen.master.Router method kwargs.
+                "kwargs": {
+                    "hostname": "..."
+                }
+            }
+
+        :param ansible_mitogen.transport_config.Spec spec:
+            Connection specification.
+        :param tuple stack:
+            Stack elements from parent call (used for recursion).
+        :param tuple seen_names:
+            Inventory hostnames from parent call (cycle detection).
+        :returns:
+            Tuple `(stack, seen_names)`.
+        """
         if spec.inventory_name() in seen_names:
             raise ansible.errors.AnsibleConnectionFailure(
                 self.via_cycle_msg % (
@@ -599,8 +627,12 @@ class Connection(ansible.plugins.connection.ConnectionBase):
     def _connect_stack(self, stack):
         """
         Pass `stack` to ContextService, requesting a copy of the context object
-        representing the target. If no connection exists yet, ContextService
-        will establish it before returning it or throwing an error.
+        representing the last tuple element. If no connection exists yet,
+        ContextService will recursively establish it before returning it or
+        throwing an error.
+
+        See :meth:`ansible_mitogen.services.ContextService.get` docstring for
+        description of the returned dictionary.
         """
         try:
             dct = self.parent.call_service(
@@ -628,6 +660,11 @@ class Connection(ansible.plugins.connection.ConnectionBase):
         self.init_child_result = dct['init_child_result']
 
     def get_good_temp_dir(self):
+        """
+        Return the 'good temporary directory' as discovered by
+        :func:`ansible_mitogen.target.init_child` immediately after
+        ContextService constructed the target context.
+        """
         self._connect()
         return self.init_child_result['good_temp_dir']
 
@@ -716,8 +753,8 @@ class Connection(ansible.plugins.connection.ConnectionBase):
 
         # #420: Ansible executes "meta" actions in the top-level process,
         # meaning "reset_connection" will cause :class:`mitogen.core.Latch` FDs
-        # to be cached and subsequently erroneously shared by children on
-        # subsequent task forks. To handle that, call on_fork() to ensure any
+        # to be cached and erroneously shared by children on subsequent
+        # WorkerProcess forks. To handle that, call on_fork() to ensure any
         # shared state is discarded.
         mitogen.fork.on_fork()
 
@@ -736,7 +773,7 @@ class Connection(ansible.plugins.connection.ConnectionBase):
         action, we cannot capture task variables via :meth:`on_action_run`.
         Instead walk the parent frames searching for the `all_vars` local from
         StrategyBase._execute_meta(). If this fails, just leave task_vars
-        unset, likely causing the wrong configuration to be created.
+        unset, likely causing a subtly wrong configuration to be selected.
         """
         frame = sys._getframe()
         while frame and not self._task_vars:

docs/ansible.rst

@@ -935,13 +935,20 @@ reporting it:
     example, Mitogen may pick the wrong username or SSH parameters.
 
     To detect this, use the special ``mitogen_get_stack`` action described
-    below to verify all the configuration variables Mitogen has chosen for the
-    connection make sense.
+    below to verify the settings Mitogen has chosen for the connection make
+    sense.
 
 **Process Environment Differences**
-    Mitogen's process model differs significantly to Ansible's in certain
-    places. In the past, bugs have been reported because Ansible plug-ins
-    modify an environment variable after Mitogen processes are started
+    Mitogen's process model differs significantly to Ansible's in many places.
+    In the past, bugs have been reported because Ansible plug-ins modify an
+    environment variable after Mitogen processes are started.
+
+    If your task's failure may relate to the process environment in some way,
+    for example, ``SSH_AUTH_SOCK``, ``LC_ALL`` or ``PATH``, then an environment
+    difference may explain it. Environment differences are always considered
+    bugs in the extension, and are very easy to repair, so even if you find a
+    workaround, please report them to avoid someone else encountering the same
+    problem.
 
 **Variable Expansion Differences**
     To avoid many classes of bugs, Mitogen avoids shell wherever possible.