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

[ezio.melotti at gmail.com]

I expanded my questions marks :)


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*.
On 2012/11/19 10:28:44, cjerdonek wrote:
> On 2012/11/19 10:08:13, ezio.melotti wrote:
> > This sentence doesn't sound too well.  Maybe "If *object* does not
have an
> > :meth:`object.__str__` method, then :func:`str` falls back on
calling
> > :meth:`object.__repr__`"?
> 
> I prefer saying what the function "returns" rather than what it
"calls," because
> it is more to the point.  I also wanted to parallel the first
sentence.  By the
> way, it calls repr() (PyObject_Repr) rather than object.__repr__(). 
Given that,
> can you suggest other wording you would prefer?

The problem I have with this sentence is that it's not clear if the
subject is "representation" or "repr", so it sounds wrong.
New suggestion:
"If *object* does not have an :meth:`object.__str__` method, then
:func:`str` falls back to returning :meth:`repr(object) <repr>`."
There's no need to explain here what the repr is.  Also this might be
slightly inaccurate, because IIRC str() might make some other changes
after calling PyObject_Repr (but I haven't looked at the code).

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
It's not clear to me what "in this case" means here.
If it means "in the case where the object is a bytes object", then it's
redundant and should be removed (hence my suggestion).
If it means "in the case where at least encoding or errors is given",
then it's not clear, and since the sentence is already in this paragraph
it shouldn't be necessary to specify it again.

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 suggested to replace "mode" with "b.__str__()" because the term "mode"
suggests to me something that can be specified with a flag or similar. 
I wouldn't call any combination of args/kwargs a different "mode".
Another disadvantage of referring to first and second mode is that the
user has to keep track of what the two modes are, and while this is
arguably a trivial task, it's IMHO better to be explicit.  (I could go
more in detail if you want, but it's probably easier if we move the
discussion on IRC.)

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