Tweak comments as suggested in review

Thanks to bitprophet and ploxiln.

3 files changed, 6 insertions, 4 deletions

diff --git a/paramiko/common.py b/paramiko/common.py
index 3b18858b..8ce735d7 100644
--- a/paramiko/common.py
+++ b/paramiko/common.py
@@ -163,15 +163,16 @@ else:
 
 
 def asbytes(s):
+    """Coerce to bytes if possible or return unchanged."""
     if isinstance(s, bytes_types):
         return s
     if isinstance(s, text_type):
-        # GZ 2017-05-25: Accept text and encode as utf-8 for compatibilty only.
+        # Accept text and encode as utf-8 for compatibility only.
         return s.encode("utf-8")
     asbytes = getattr(s, "asbytes", None)
     if asbytes is not None:
         return asbytes()
-    # May be an object that implements the buffer api, let callers decide
+    # May be an object that implements the buffer api, let callers handle.
     return s
 
 
diff --git a/paramiko/file.py b/paramiko/file.py
index 35637b8e..a1bdafbe 100644
--- a/paramiko/file.py
+++ b/paramiko/file.py
@@ -392,8 +392,7 @@ class BufferedFile (ClosingContextManager):
         :param data: ``str``/``bytes`` data to write
         """
         if isinstance(data, text_type):
-            # GZ 2017-05-25: Accepting text on a binary stream unconditionally
-            # cooercing to utf-8 seems questionable, but compatibility reasons?
+            # Accept text and encode as utf-8 for compatibility only.
             data = data.encode('utf-8')
         if self._closed:
             raise IOError('File is closed')
diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py
index ef04f37a..a1ee6723 100644
--- a/paramiko/sftp_client.py
+++ b/paramiko/sftp_client.py
@@ -761,6 +761,8 @@ class SFTPClient(BaseSFTP, ClosingContextManager):
                 elif isinstance(item, SFTPAttributes):
                     item._pack(msg)
                 else:
+                    # For all other types, rely on as_string() to either coerce
+                    # to bytes before writing or raise a suitable exception.
                     msg.add_string(item)
             num = self.request_number
             self._expecting[num] = fileobj