[docs] attrgetter and itemgetter signatures in docs need cleanup (issue 16523)

zachary.ware at gmail.com zachary.ware at gmail.com
Wed May 1 19:35:03 CEST 2013


Just a couple of nitpicks :)


http://bugs.python.org/review/16523/diff/8043/Doc/library/operator.rst
File Doc/library/operator.rst (right):

http://bugs.python.org/review/16523/diff/8043/Doc/library/operator.rst#newcode265
Doc/library/operator.rst:265: returns ``(r.name.first, r.name.last)``.
I think either the two semicolons should also be periods, or all three
punctuation marks should just be removed (and probably lower-case After,
as well) since it is a bulleted list.  Same applies to itemgetter and
methodcaller.

http://bugs.python.org/review/16523/diff/8043/Doc/library/operator.rst#newcode267
Doc/library/operator.rst:267: The function is equivalent to::
I think it is a little misleading to call attrgetter, itemgetter, and
methodcaller "functions" here.  They don't do anything that couldn't be
done with a function, and they do try to look like functions (without
going to extremes), but they are implemented as classes and, as such,
will tell you what they are if you use type() on them.  I don't think
that the ".. function:: ..." line should be changed to  class, because
that would change the way they are displayed and actually call them
classes, which also wouldn't be good, but I think the ambiguity of the
old wording ("Equivalent to::") was a good way to go.  It's not exactly
true, anyway, as there are some corner cases that these examples gloss
over, so maybe "Basically equivalent to::" or similar would be better.

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


More information about the docs mailing list