Close issue20653: improve functional API docs; minor code changes
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index b5fc4b6..eb5bdd98 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -374,6 +374,9 @@
With pickle protocol version 4 it is possible to easily pickle enums
nested in other classes.
+It is possible to modify how Enum members are pickled/unpickled by defining
+:meth:`__reduce_ex__` in the enumeration class.
+
Functional API
--------------
@@ -420,6 +423,12 @@
>>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__)
+.. warning::
+
+ If :param module: is not supplied, and Enum cannot determine what it is,
+ the new Enum members will not be unpicklable; to keep errors closer to
+ the source, pickling will be disabled.
+
The new pickle protocol 4 also, in some circumstances, relies on
:attr:`__qualname__` being set to the location where pickle will be able
to find the class. For example, if the class was made available in class
@@ -427,6 +436,31 @@
>>> Animals = Enum('Animals', 'ant bee cat dog', qualname='SomeData.Animals')
+The complete signature is::
+
+ Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>)
+
+:param value: What the new Enum class will record as its name.
+
+:param names: The Enum members. This can be a whitespace or comma seperated
+string::
+
+ 'red green blue', 'red,green,blue', 'red, green, blue'
+
+(values will start at 1), or an iterator of name, value pairs::
+
+ [('cyan', 4), ('magenta', 5), ('yellow', 6)]
+
+or a mapping::
+
+ {'chartruese': 7, 'sea_green': 11, 'rosemary': 42}
+
+:param module: name of module where new Enum class can be found.
+
+:param qualname: where in module new Enum class can be found.
+
+:param type: type to mix in to new Enum class.
+
Derived Enumerations
--------------------