search

jcorbino / mole

Mimetic Operators Library Enhanced
GNU General Public License v3.0
25 stars 19 forks source link

[JOSS review] C++ Documentation #16

Closed jakelangham closed 3 months ago

jakelangham commented 4 months ago

As part of the ongoing reviews at https://github.com/openjournals/joss-reviews/issues/6288, I have a query about documentation for MOLE. I can see that there is some documentation for the MATLAB part of the library (in the form of the quick start guide), which I was able to follow (though it does not cover everything, as far as I can tell).

Is there equivalent documentation available for the C++ library? The auto-generated doxygen html files cannot really be counted as documentation because they do not specify what any of the functions do. (Compare for example, to the API docs of Armadillo https://arma.sourceforge.net/docs.html where every function, operator and so on are fully specified, often with usage examples.)

I found that I could only get to grips with what the given examples were doing by reading the code for the library directly. An ordinary user that just wants to set up and solve a problem using MOLE ought not to have to do this.

jcorbino commented 3 months ago

@jakelangham Thank you for bringing this issue to my attention. Improving the documentation is indeed a high priority for me. In the meantime, to address your concerns and meet the journal's requirements, I have:

  1. Expanded the C++ Doxygen documentation by adding more detailed information to the files, classes, and functions.

  2. Created a quick guide specifically for C++ users.

I am committed to enhancing the scope and quality of MOLE's documentation, and I'll get additional support this Fall to make further improvements.

jcorbino commented 3 months ago

@jakelangham , I'm just following up; please let me know if there's anything else I might be missing.

jakelangham commented 3 months ago

Hi @jcorbino, I appreciate the work you've put into this. The pdf guide is especially welcome.

The API docs could be improved quite a lot still, so consider continuing to add to them in the future, with more high-level information about how the underlying methods work. Nevertheless, I think there is enough there for new users to satisfy the requirements for the review.