[docs] [issue8840] truncate() semantics changed in 3.1.2

[Martin Panter]

Martin Panter added the comment:

In general I agree with the doc strings giving the main details, and leaving smaller details for the reference documentation. Maybe for concrete implementations like BytesIO, it is not worth saying the expanded contents are undefined. One other way to make them shorter is to drop “as reported by tell()”.

diff --git a/Lib/_pyio.py b/Lib/_pyio.py
@@ -344,10 +344,12 @@
     def truncate(self, pos=None):
+        """Resize stream to at most size bytes.

Wouldn’t it be more correct to say “at most ‘pos’ bytes”?

You should avoid mentioning byte sizes for TextIOBase.truncate(); see Issue 25849. Also applies to the StringIO subclasses.

+        Position in the stream is left unchanged.  Size defaults to

I think it should be “The position in the stream . . .”, to match the other full sentences in these paragraphs.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue8840>
_______________________________________