[docs] Code, test, and doc review for PEP-0435 Enum (issue 17947)

[eliben at gmail.com]

http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst
File Doc/library/enum.rst (right):

http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode240
Doc/library/enum.rst:240: of *_sunder_* names, *__dunder__* names, and
descriptors; methods are
The specific rules are not well-enough defined. sunder names are
forbidden, dunders are not - is this explained elsewhere?

http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode245
Doc/library/enum.rst:245: methods.
This needs some more explanation and/or example, perhaps somewhere in
the end in "advanced customization"

http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode260
Doc/library/enum.rst:260: But this is allowed::
Can this have a sensical example? (like, some simple example of where
this actually makes sense)

http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode280
Doc/library/enum.rst:280: A variation of :class:`Enum` is proposed which
is also a subclass of :class:`int`.
80 col

http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode331
Doc/library/enum.rst:331: Other derived enumerations
I think this should be merged somehow with the "interesting examples",
perhaps in a higher-level header: "Creating custom enumerations" with
some dry explanation of the semantics, followed by examples. And this
should definitely be the last section of the document :-)

http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode340
Doc/library/enum.rst:340: This demonstrates how similar derived
enumerations can be defined, for example
; instead of , after "defined" ?

http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode443
Doc/library/enum.rst:443: ...                     )
just append this to the previous line

http://bugs.python.org/review/17947/diff/8332/Lib/enum.py
File Lib/enum.py (right):

http://bugs.python.org/review/17947/diff/8332/Lib/enum.py#newcode42
Lib/enum.py:42: """Returns True if a sunder name, False otherwise."""
Unlike "dunder", "sunder" has no historical meaning for python
programmers. I suggest a more consistent documentation then, like:

"Returns True if a __dunder__ name, False otherwise"
"Returns True if a _sunder_ name, False otherwise"

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