[JOSS Review]: Docstrings

[joewallwork]

Towards openjournals/joss-reviews#7949.

It's great that elfe3D includes a manual and PhD thesis, as well as API documentation that can be generated using Doxygen. However, I feel that the API documentation isn't as useful as it could be because the docstrings don't give any information about the input variables. For example, calculate_elemental_residuals has input arguments m, w, s, etc. and it's unclear what these variables represent and what values should be passed.

It'd be great if variable descriptions could be added to the docstrings to improve the API documentation.

[emgeopaula]

Thanks for suggesting this. The Doxygen documentation does indeed not directly give detailed information on the arguments passed to subroutines, but it does provide information on the variable types. Just below the input variable list, I can click on a link that brings me directly to the variable definitions in the corresponding source code lines. I agree that the variable descriptions can be commented in more detail in some subroutines and I will work on improving the code comments. However, all global variables are described in the Variable Definitions list at the beginning of elfe3D.f90, which is easily accessible via a similar link in the Doxygen File list. I would like to omit adding more detail to the Doxygen, as I feel that possible contributors will rather have a detailed look into the code itself and the thesis. Users can simply look into the manual, where they find necessary information about input variables.
Let me know what you think!

[joewallwork]

I agree that the variable descriptions can be commented in more detail in some subroutines and I will work on improving the code comments.

That'd be great, thanks.

However, all global variables are described in the Variable Definitions list at the beginning of elfe3D.f90, which is easily accessible via a similar link in the Doxygen File list.

Oh, good point - I hadn't noticed that. Perhaps this could be mentioned in the elfe3D/README.md file?

I would like to omit adding more detail to the Doxygen, as I feel that possible contributors will rather have a detailed look into the code itself and the thesis. Users can simply look into the manual, where they find necessary information about input variables.

Sure, that makes sense.

[emgeopaula]

I agree that the variable descriptions can be commented in more detail in some subroutines and I will work on improving the code comments.

That'd be great, thanks.

Will do.

However, all global variables are described in the Variable Definitions list at the beginning of elfe3D.f90, which is easily accessible via a similar link in the Doxygen File list.

Oh, good point - I hadn't noticed that. Perhaps this could be mentioned in the elfe3D/README.md file?

I have included the information in docs/README.md.

I would like to omit adding more detail to the Doxygen, as I feel that possible contributors will rather have a detailed look into the code itself and the thesis. Users can simply look into the manual, where they find necessary information about input variables.

Sure, that makes sense.

[joewallwork]

Thanks @emgeopaula. With that, I'm happy to complete the checklist on the review.