isl-org / isl-org/Open3D

No names of arguments in python API documentation of visualization.gui.Application methods

Open
#6,042 0 comments 0 reactions 0 assignees View on GitHub
question
Dominant language
C++
Stars
14k
Forks
2.6k
Avg merge
5d 18h
Merged PRs (30d)
6

Description

### Checklist

- [X] I have searched for [similar issues](https://github.com/isl-org/Open3D/issues).
- [X] For Python issues, I have tested with the [latest development wheel](http://www.open3d.org/docs/latest/getting_started.html#development-version-pip).
- [X] I have checked the [release documentation](http://www.open3d.org/docs/release/) and the [latest documentation](http://www.open3d.org/docs/latest/) (for `master` branch).

### My Question

When looking at the documentation for a method in the class `gui.application.Application` e.g. [`Application.render_to_image`](
http://www.open3d.org/docs/latest/python_api/open3d.visualization.gui.Application.html#open3d.visualization.gui.Application.render_to_image), the arguments have generic names `arg0`, `arg1`, `arg2`, and they are not described - we see only that `arg1` and `arg2` are `int`'s, but there is no indication of their meaning.

In this case, to find out the meaning of the parameters we need to search in the [pybind code at `cpp/pybind/visualization/gui/gui.cpp`](https://github.com/isl-org/Open3D/blob/4d63591ce020651d907519b8ed84eb4e903a4442/cpp/pybind/visualization/gui/gui.cpp#L331-L339).

In other cases, it is necessary to first find in the pybind code which C++ function is called and with which arguments, then to look up the C++ documentation of the underlying function, e.g. here [`open3d::visualization::gui::Application::RenderToImage`](http://www.open3d.org/docs/latest/cpp_api/classopen3d_1_1visualization_1_1gui_1_1_application.html#a928d2a5cb11e998fce3121443abc010e).

This does not seem to be the case an issue in other parts of the library like [`o3d.geometry.Geometry3D`](http://www.open3d.org/docs/latest/python_api/open3d.geometry.Geometry3D.html#open3d.geometry.Geometry3D) where the arguments are almost always named, and documented, apparently using `docstring::ClassMethodDocInject`.

I believe the pybind code should be improved either with `docstring::ClassMethodDocInject` or using `py::arg` - is that right?

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.