I am nearly complete with my JOSS review (openjournals/joss-reviews#10124) with the last checkmark being "Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?"
The examples section is spectacular, with explanations of what you can do with various commands, example commands, note and tip call-outs, and results. I would love to see the same for the API documentation. For instance, here in main I would like to see the command line arguments listed with an explanation of what they do.
An explanation of the common keys and values in dic would be super-helpful for contributors and people wanting to customize functionality.
For check_cmdargs knowing what command flags are being checked could be handy.
In, say coarser_grid how do you modify dic to set how much to coarsen the grid?
How does add_lost_pv_to_bundary_cells work? When do you call it?
And similar questions for the functions exposed by the API.
I am nearly complete with my JOSS review (openjournals/joss-reviews#10124) with the last checkmark being "Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?"
The examples section is spectacular, with explanations of what you can do with various commands, example commands, note and tip call-outs, and results. I would love to see the same for the API documentation. For instance, here in main I would like to see the command line arguments listed with an explanation of what they do.
An explanation of the common keys and values in
dicwould be super-helpful for contributors and people wanting to customize functionality.For check_cmdargs knowing what command flags are being checked could be handy.
In, say coarser_grid how do you modify
dicto set how much to coarsen the grid?How does add_lost_pv_to_bundary_cells work? When do you call it?
And similar questions for the functions exposed by the API.