On 13/08/14 18:09, Vadim Zeitlin wrote:

 Another big problem in the Python documentation for our API is that we use
a lot of enums and their structure completely disappears in translation,
i.e. the documentation for the enum type itself is just lost because it
doesn't exist in Python at all and the parameters of enum types become less
clear because they are all just ints in the Python documentation.

 This is not a Doxygen problem at all though, clearly nothing can be done
about it with the current way of wrapping enums. So I'd like to propose
adding another, generally better and also Python 3 compatible way of
wrapping them and instead of just defining module level constants, as is
done now, create classes corresponding to the enums and put the constants
inside them.

 E.g. currently the following declaration:

	/// Some colors.
	enum color {
	    RED,    ///< 620-740 nm.
	    BLUE,   ///< 450-495 nm.
	    GREEN   ///< 495-570 nm.

results in the following Python code being generated:

	RED = _d.RED
	r""" 620-740 nm."""
	r""" 450-495 nm."""
	r""" 495-570 nm."""

and I'd like to generate the following instead:

	class color:
	    """Some colors."""
	    RED = _d.RED
	    r""" 620-740 nm."""
	    BLUE = _d.BLUE
	    r""" 450-495 nm."""
	    GREEN = _d.GREEN
	    r""" 495-570 nm."""
This looks a lot like the equivalent to what is used in Java to create enum classes out of enums. See the various ways of changing the ways enums are wrapped for Java at http://swig.org/Doc3.0/Java.html#Java_enumerations. See the Typesafe enums.
or, in Python 3 case,

	from enum import Enum
	class color(Enum):
	   ... the rest is the same as above ...

 This is backwards incompatible, of course, so would require either
explicitly %including some "enumclass.swg" or using a %feature, what would
be preferred here?
If you can implement it so that it is enabled like it is in Java and CSharp, that would be ideal. However, these implementations rely a lot on typemaps for the Proxy class generation, and Python does not... so is probably not going to be possible. However, the idea of %include of a new file to turn it on is exactly how it is implemented.

 But except for compatibility concerns, I only see advantages in wrapping
enums like this: this is safer, more clear, compatible with Python 3 and,
of course, incidentally allows me to solve my documentation problem.

 Please let me know if I'm missing any potential problems here.

 As always, thanks in advance for your comments,

One other thing is C++11 enum classes should turn on this type of proxy class wrapping by default. However, no attempt at implementing C++11 enum classes has yet been done in Python, although there it has been in Java.