[docs] add a "class str" entry to the docs (issue 16209)

chris.jerdonek at gmail.com chris.jerdonek at gmail.com
Wed Nov 28 06:06:05 CET 2012


Reviewers: ezio.melotti,


http://bugs.python.org/review/16209/diff/6684/Doc/extending/newtypes.rst
File Doc/extending/newtypes.rst (right):

http://bugs.python.org/review/16209/diff/6684/Doc/extending/newtypes.rst#newcode986
Doc/extending/newtypes.rst:986: single: string; object presentation
On 2012/11/27 18:04:38, ezio.melotti wrote:
> representation?

I changed this.  If you think this should be changed, the section title
should probably be changed as well.  Note that an argument could be made
that "presentation" is better than "representation".  The latter
connotes the internal representation of an object, whereas presentation
connotes how something should be presented to others (which is what
str/repr do).

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

http://bugs.python.org/review/16209/diff/6684/Doc/library/functions.rst#newcode1246
Doc/library/functions.rst:1246: See the :class:`str` type for
documentation of ``str()``.
On 2012/11/27 18:04:38, ezio.melotti wrote:
> This sounds a bit confusing and redundant to me.
> There are two links to textseq with two different texts, two to
:class:`str` (I
> think that's somewhere near textseq), and ``str`` is used 4 more
times.
> 
> I think all this (including the following line) can be summarized to:
> Return a :class:`str` version of *object*.
> See also the documentation of the :class:`str` type and :ref:`textseq`
for more
> information about strings.

I simplified the wording.  Note that I think it is important to state
explicitly rather than implicitly that str is a type since readers are
going to the entry expecting a function, so this should be made
unambiguously clear.

Regarding occurrences of "str", one of those occurrences was because I
wanted to avoid referring to the entry as "this function" or "the [str]
constructor."  In an earlier, similar issue you commented against using
either term for built-in functions that correspond to types.



Please review this at http://bugs.python.org/review/16209/

Affected files:
  Doc/c-api/object.rst
  Doc/extending/newtypes.rst
  Doc/library/functions.rst
  Doc/library/stdtypes.rst
  Doc/reference/datamodel.rst




More information about the docs mailing list