Allow adding docstrings to the classes created with create_exception!

[fjarri]

At the moment the recommended way of creating custom exceptions is the create_exception! macro. Unfortunately, it does not allow a docstring to be specified (since that docstring will be attached to the macro invocation and not to the actual class it creates), which leads to several problems:

• Rust compiler gives a missing docstring warning, which cannot be silenced by #[allow(missing_docs)] (for the same reason an actual docstring cannot be specified)
• One cannot define a docstring for the created exception and have it picked up by introspecting tools on the Python side (like help() in REPL, or sphinx.autodoc)

I tried doing an analogue of class MyError(Exception): pass in Rust (that's really all I need), but couldn't figure out how to write a constructor.

[davidhewitt]

Personally I'd prefer not solve this and instead finish refining #[pyclass] for creating exceptions (#295)

[davidhewitt]

(help with finishing the final bits of design and implementation written there is very much wanted!)

[fjarri]

Yes, that seems reasonable. Is there some workaround one could use at the moment? I would like to be able to call the custom exception as a regular Exception, with a string message as a parameter, but for that I need to create a new PyException object in the constructor, and it doesn't seem to have anything but new_err() available.

[mejrs]

The impl_native_exception macro takes a docstring as argument, perhaps we should update the other macros to do this too? See https://github.com/PyO3/pyo3/blob/main/src/exceptions.rs#L210

[davidhewitt]

Good suggestion - adding an optional final argument would be backwards-compatible!