minor updates to network connection plugins (#23043)

* removes unused log() function in network_cli
* adds method comments to terminal plugin base

lib/ansible/plugins/connection/network_cli.py

@@ -58,10 +58,6 @@ class Connection(_Connection):
         if play_context.verbosity > 3:
             logging.getLogger('paramiko').setLevel(logging.DEBUG)
 
-    def log(self, msg):
-        msg = 'h=%s u=%s %s' % (self._play_context.remote_addr, self._play_context.remote_user, msg)
-        logger.debug(msg)
-
     def update_play_context(self, play_context):
         """Updates the play context information for the connection"""
 

lib/ansible/plugins/terminal/__init__.py

@@ -32,10 +32,13 @@ class TerminalBase(with_metaclass(ABCMeta, object)):
     A base class for implementing cli connections
     '''
 
+    # compiled regular expression as stdout
     terminal_stdout_re = []
 
+    # compiled regular expression as stderr
     terminal_stderr_re = []
 
+    # copiled regular expression to remove ANSI codes
     ansi_re = [
         re.compile(r'(\x1b\[\?1h\x1b=)'),
         re.compile(r'\x08.')
@@ -45,24 +48,52 @@ class TerminalBase(with_metaclass(ABCMeta, object)):
         self._connection = connection
 
     def _exec_cli_command(self, cmd, check_rc=True):
+        """Executes a CLI command on the device"""
         rc, out, err = self._connection.exec_command(cmd)
         if check_rc and rc != 0:
             raise AnsibleConnectionFailure(err)
         return rc, out, err
 
     def _get_prompt(self):
+        """ Returns the current prompt from the device"""
         for cmd in ['\n', 'prompt()']:
             rc, out, err = self._exec_cli_command(cmd)
         return out
 
     def on_open_shell(self):
+        """Called after the SSH session is established
+
+        This method is called right after the invoke_shell() is called from
+        the Paramiko SSHClient instance.  It provides an opportunity to setup
+        terminal parameters such as disbling paging for instance.
+        """
         pass
 
     def on_close_shell(self):
+        """Called before the connection is closed
+
+        This method gets called once the connection close has been requested
+        but before the connection is actually closed.  It provides an
+        opportunity to clean up any terminal resources before the shell is
+        actually closed
+        """
         pass
 
     def on_authorize(self, passwd=None):
+        """Called when privilege escalation is requested
+
+        This method is called when the privilege is requested to be elevated
+        in the play context by setting become to True.  It is the responsibility
+        of the terminal plugin to actually do the privilege escalation such
+        as entering `enable` mode for instance
+        """
         pass
 
     def on_deauthorize(self):
+        """Called when privilege deescalation is requested
+
+        This method is called when the privilege changed from escalated
+        (become=True) to non escalated (become=False).  It is the responsibility
+        of the this method to actually perform the deauthorization procedure
+        """
         pass