Non-normative docstrings

[brandondube]

This issue is part of my portion of the JOSS review, openjournals/joss-reviews#5478

The revised documentation's contributing page shows how to document code, and elucifies that you are using something other than python docstrings to document functions. This choice breaks completions for editors, jupyter kernels, etc, and will hamper users' ability to interact in the usual ways with your code when consuming it. I would recommend documenting the python API using any of the standards for python docstrings; numpy style, google style, sphinx style, etc.

This is not mandatory, just a suggestion to help your software gain traction among python users

[arendMoerman]

Thank you for the suggestion. We have investigated the possibilities and have come to the conclusion that doxygen does support special commands in docstrings, with the help of a little extra formatting:
"""!

"""
This is supported by doxygen and its special commands, but comes at the cost of an extra exclamation mark after the first quote triplet which might not comply with a common style but at least adds the docstring to the doc attribute of a function.
We have already implemented this in the entire src/PyPO/ directory (source directory), but not yet for the GUI source code. We will do this in due time.

The updated documenting style (using docstrings) is now also reflected in the documentation itself.

Could you please let us know if this satisfies your suggestion?

[arendMoerman]

The GUI source code has now also been updated to contain the docstrings instead of the old style.

[brandondube]

Thank you. One nit: your docs say:

Because docstrings cannot be used as file descriptions, we use a different style to describe files. Just as for C/C++/CUDA, file descriptions go after import statements and before the classes and/or methods in the file:

If the first line of a python file is a string, that is the docstring for the file. For example, prysm:

https://github.com/brandondube/prysm/blob/master/prysm/__init__.py#L1

and

>>> prysm.__doc__
'prysm, a python optics module.'