Many C++ methods have no description in docs

[landreman]

There are a bunch of methods defined in C++, such as gamma() for surfaces and curves, that do not have any description in the API docs, or when a user uses help().

[landreman]

Do we want only the functions without _impl to appear in the API docs?

[smiet]

Hi @landreman, @florianwechsung,

I would love to get on this (part-time), I rely on the docstrings of functions a lot!

Won't be an overnight thing, but I am planning on making a branch cpp_docstrings (that others are of course also free to help with!)

Before I get started, I quickly want to run the strategy by you, as I see three different ways to do the documentation:

1. directly add docstrings in the python.cpp and python_[subclass].cpp files, by including it in the m.def() declarations, where the module is defined.

   • Pros: quick. Exsisting documentation is is defined like this
   • Cons: The module definition will become very long and hard to read. documentation far from source, though still cluttering code.

2. Add the documentation to the .h files using the `PYBIND11_DOC(my_function, "some documentation")' macro above each function header definition

   • Pros: uses intended Pybind11 conventions. Documentation close to source related to it.
   • Cons: lots. of. files. to. visit.

3. Generate docstrings themselves using sfinx, starting with @autodoc.docstring decorators.

   • Pros: immediately adds basic documentation, documentation neatly separated from source.
   • Cons: Another dependency. Unfamiliar to me. Adds extra dependency on sfinx also for running(?)

Which option is best in your opinion? I am leaning towards option 2, comments are welcome.