Closed Chilipp closed 3 years ago
This might take a little time, but I am working on it.
API Documentation completed for the Launcher, DynaGUI Alarms and DynaGUI TF. This has been pushed to Git. DynaGUI NV API documentations remains and is being worked on at the moment.
Hey @benjaminbolling! thanks for adding some comments to the code. The question is a bit here, what JOSS exactly requires as an API documentation. A common format of an API reference would be something like https://psyplot.readthedocs.io/projects/psy-view/en/latest/api/psy_view.html or http://xarray.pydata.org/en/stable/api.html. From my perspective, I think your approach is well enough as your main focus is on the usage of the GUI, and not on the Python API. But I'll ask the editor about this
Dear @Chilipp, thank you so much for your comments. I have elaborated the API documentation for the DynaGUI NV as well now, and await @majensen (assuming he is the editor) for comments on this. Hopefully this tagging works! :)
Hi @benjaminbolling: I think this is good. What I would do is the following one simple trick: for all the methods where you have a comment following the def
, such as
def __init__(self, ctrl_library, inp, parent=None):
# Initialization of the GUI with a control library and an input
triple-quote the comment instead:
def __init__(self, ctrl_library, inp, parent=None):
"""Initialization of the GUI with a control library and an input"""
This will turn that comment into the doc line for the method. Then it will be visible to things like pydoc
, and can also be parsed for fancier rendering as in the pages that @Chilipp referred to.
If we do that, I think we can call it good.
(note triple-quotes leave the line breaks in, so for example, do
def myfunc(self):
"""This is a multi-line docstring:
Second line
Third line
""""
and this will preserve the line-breaks in the downstream formatters)
Good morning! Thank you for your comments/suggestions, I have implemented these changes to all the Python files.
thanks @benjaminbolling!
As a requirement for the review in https://github.com/openjournals/joss-reviews/issues/1942, please add an API documentation to your python source code.
See https://realpython.com/documenting-python-code/ for instance about what I mean with this. At least the central objects of your software should be documented properly.