Reword docs/changelog re #315

2 files changed, 22 insertions, 17 deletions

diff --git a/paramiko/file.py b/paramiko/file.py
index 725ca5f6..70243e40 100644
--- a/paramiko/file.py
+++ b/paramiko/file.py
@@ -124,15 +124,14 @@ class BufferedFile (object):
         file first).  If the ``size`` argument is negative or omitted, read all
         the remaining data in the file.
 
-        `'b' mode flag is ignored (self.FLAG_BINARY in self._flags), because
-        SSH treats all files as binary, since we have no idea what encoding
-        the file is in, or even if the file is text data.
-  
+        ``'b'`` mode flag is ignored (``self.FLAG_BINARY`` in ``self._flags``),
+        because SSH treats all files as binary, since we have no idea what
+        encoding the file is in, or even if the file is text data.
 
         :param int size: maximum number of bytes to read
         :return:
-            data read from the file (as bytes ), or an empty string
-            if EOF was encountered immediately
+            data read from the file (as bytes), or an empty string if EOF was
+            encountered immediately
         """
         if self._closed:
             raise IOError('File is closed')
@@ -193,10 +192,10 @@ class BufferedFile (object):
         :return:
             next line of the file, or an empty string if the end of the
             file has been reached.
-            If the file was opened in binary 'b' mode: bytes are returned
-            Else: the encoding of the file is assumed to be utf-8 (default
-            encoding used by paramiko.py3compat.u) and character strings
-           (`str`) are returned
+
+            If the file was opened in binary (``'b'``) mode: bytes are returned
+            Else: the encoding of the file is assumed to be UTF-8 and character
+            strings (`str`) are returned
         """
         # it's almost silly how complex this function is.
         if self._closed:
diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst
index 67c4f827..8a4b0f56 100644
--- a/sites/www/changelog.rst
+++ b/sites/www/changelog.rst
@@ -2,13 +2,19 @@
 Changelog
 =========
 
-* :bug: BufferedFile.read() now returns byte strings instead of text strings
-  It is the right thing to do since we have no idea what encoding the file 
-  is in, or even if the file is text data. BufferedFile.readline() is
-  unchanged and returns text strings assuming the file is utf-8 encoded.
-  This should fix the following issue:
-  http://comments.gmane.org/gmane.comp.sysutils.backup.obnam/252  
-  Thanks Antoine Brenner
+* :bug:`-` `paramiko.file.BufferedFile.read` incorrectly returned text strings
+  after the Python 3 migration, despite bytes being more appropriate for file
+  contents (which may be binary or of an unknown encoding.) This has been
+  addressed.
+
+  .. note::
+      `paramiko.file.BufferedFile.readline` continues to return strings, not
+      bytes, as "lines" only make sense for textual data. It assumes UTF-8 by
+      default.
+
+  This should fix `this issue raised on the Obnam mailing list
+  <http://comments.gmane.org/gmane.comp.sysutils.backup.obnam/252>`_.  Thanks
+  to Antoine Brenner for the patch.
 * :bug:`-` Added self.args for exception classes. Used for unpickling. Related
   to (`Fabric #986 <https://github.com/fabric/fabric/issues/986>`_, `Fabric
   #714 <https://github.com/fabric/fabric/issues/714>`_). Thanks to Alex