The API documentation is hard to expand

[edgar-bonet]

This is a followup on pull request #282 from the RedPitaya repository:

The documentation of the C and Python APIs is very terse, and some functions would benefit from more detailed explanations, examples, etc. However, as it is formatted now, this documentation is hard to expand:

• the function descriptions have to be manually line-wrapped
• they have then to be inserted into ASCII-art-like tables (RST tables)
• they must fit into small boxes that are not amenable to long explanations
• if they overflow the box width, the whole table has to be reformatted to a wider size
• as the lines are up to 296 characters long, the user must use either a very wide monitor or a small font.

This command list has, near the top of the page, a link to the C header files meant to provide a “detailed description”. These headers do carry descriptions in the form of Doxygen comments, but these are about as terse as the command list itself.

I have no good solution to this problem. Maybe the command list should be formatted in a way that is more amenable to expansion? Maybe there is a better way to make use of the Doxygen comments?

I would like to point out that the Doxygen documentation is easier to maintain and, because it lives close to the source code, it is also easier to keep up to date. A coworker told me that SWIG can translate Doxygen comments to Python docstrings, which Spinx can then process. Maybe this could be worth exploring.

[Lightsaver7]

Hello Edgar,

Sorry for the late reply. I merged the two branches you committed - thank you.

I will look into ways to make it easier to document and display data on each command.

Miha

[Lightsaver7]

I think we will keep the tables for now, but in the future we will make a separate page for each command, where the full functionality of each function is explained in detail together with some examples.

[Lightsaver7]

In the latest update of docs, I have separated the commands into sections and started adding additional explanation (overall functionality) to each of the sections. I plan to expand this further and likely add a page for each of the commands with links to the source code.