[docs] [issue23738] Clarify documentation of positional-only default values

[Martin Panter]

Martin Panter added the comment:

Here is a more conservative patch using square brackets, and documenting the defaults in the text. I updated all the documentation from my previous patch, and added new changes for the “io” module.

One quirk was that BufferedReader.read1() does not actually support the value −1. Therefore I changed the base class to BufferedIOBase.read1([size]) without mentioning what happens when size is omitted. Related: Issue 23214.

----------
Added file: http://bugs.python.org/file41253/square-brackets.patch

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