[QUESTION] For enums, how to change the docstring for __init__()?

[andioz]

Yesterday I had chance to discuss my question with @YannickJadoul and @bstaletic in gitter, starting here: https://gitter.im/pybind/Lobby?at=5f97172661007f7d1b979a2b. It was big fun and very fruitful! nevertheless I want to report the issue here, and summarize the workaround we found.

I have a simple enumeration with a standard binding:

  enum class Hand {LEFT, RIGHT};

  py::enum_<Hand> hand{parent, "Hand", "Hand enumeration."};
  hand.value("LEFT", Hand::LEFT, "Left hand enumeration value.");
  hand.value("RIGHT", Hand::RIGHT, "Right hand enumeration value.");

The docstring looks like this now:

Docstring:     
Hand enumeration.

Members:
  LEFT : Left hand enumeration value.
  RIGHT : Right hand enumeration value.

Init docstring: __init__(self: example.Hand, arg0: int) -> None

I don't like the arg0: int part, therefore I want to change this, to be consistent with the rest of my bindings, where I give every arguiment a name. My first, naive try:

  hand.def(py::init<long>(), py::arg("value"), "Default initializer.");

This doesn't compile. I started a chat on gitter with this, and we came to the following workaround:

  py::delattr(hand, "__init__");
  hand.def(
    py::init([] (std::underlying_type_t<Hand> value) { return static_cast<Hand>(value); }),
    py::arg("value"), 
    "Default Initializer."
  );

Now, everything looks like I wanted. And hopefully, no negative side-effects. But this is more a hack than a clean solution, right?

The question is now: would it be possible to implement a way for docstring customization for enums (and maybe other predefined components, methods, functions, etc)?

And as @YannickJadoul mentioned in the chat, maybe the default names for some method arguments should be changes to be more readable (value for enums init, other for __eq__ and so on)?

I know this is not very important, more the icing on the cake, but it would be nice to have a comlpete, clean, and documented way to accomplish good names in all docstrings.

[YannickJadoul]

@YannickJadoul linked a pull request that will close this issue 22 hours ago

See, @andioz? ;-)

[andioz]

Solved by good default names