[docs] Improve doc for str(bytesobject) (issue 13538)

[chris.jerdonek at gmail.com]

http://bugs.python.org/review/13538/diff/6626/Doc/library/functions.rst
File Doc/library/functions.rst (right):

http://bugs.python.org/review/13538/diff/6626/Doc/library/functions.rst#newcode1268
Doc/library/functions.rst:1268: representation :func:`repr` of *object*.
Your new suggestion is fine.  Thanks.  Also, the code is here:

http://hg.python.org/cpython/file/cf606c403f14/Objects/object.c#l397

It just returns what PyObject_Repr returns.

http://bugs.python.org/review/13538/diff/6626/Doc/library/functions.rst#newcode1277
Doc/library/functions.rst:1277: :class:`bytes` (or :class:`bytearray`)
object in this case, then
The latter was intended.  This may be clearer if "In this case" is at
the beginning of the sentence.  Without the phrase, it has an ambiguous
feeling to me.  The second sentence could be interpreted to be an
additional implication rather than a refinement of the previous
implication.  For example, the first sentence says that *object* needs
to be a bytes object.  The second sentence could then be saying what
happens for bytes objects, but in all cases.  That also seems like a
natural way of explaining something.

I also feel the extra clarity is deserved here because this point about
bytes is a source of confusion -- so much so that we added an extra
paragraph and example to clarify.  I realize that if the reader reads
the next paragraph, it will dispel the ambiguity we're discussing here,
but I think it's worth having the paragraph be unambiguous when read
alone.

http://bugs.python.org/review/13538/diff/6626/Doc/library/functions.rst#newcode1285
Doc/library/functions.rst:1285: or *errors* arguments uses the first
mode of returning the informal string
I don't especially like the word "mode" either. :)  I was just keeping
with what was originally used in the first sentence of the str() docs. 
Why didn't you object to it there? :)

Can you suggest a rephrasing of the first sentence ("... using one of
the following two modes.") that allows us to use parallel phrasing in
the subsequent paragraphs?  I like telling the reader in advance that
there are two of "something" and because it parallels the two
signatures.  Also, saying first or second helps because then the reader
knows whether to look in the first or second of the two paragraphs
(without having to interpret the text and then map it to the
corresponding paragraph themselves).  Both may be best (number and
description).

http://bugs.python.org/review/13538/