API documentation

[Armavica]

Hi, as part of the review that I am doing for JOSS (openjournals/joss-reviews#9384), I have to evaluate the following item:

Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?

Although diffsol provides many examples and tutorials, I think that this item is rather targeted towards the documentation provided with doc-strings and appearing on the docs.rs documentation.

I am not quite sure what could be considered "core functionality" of this library, and I think that it might be fine if private modules and functionalities are not documented as extensively as public-facing ones. However, while some structs are very well documented (example), documentation seems to be lacking for others (example). Would it be possible to add struct-level or function-level documentation for the structs susceptible to be manipulated by users? Notably, it looks like several of the structs and traits re-exported at crate root level (can this be considered the "core functionality"?) are missing an element-level documentation (DiffSl, JacobianColoring, OdeEquationsStoch, etc.)

I think that it would also good to add a couple lines of module-level documentation, to appear in this section, for modules and submodules. It is fine to mention if modules or submodules are not intended for public use (although documenting them might still be helpful for new contributors to diffsol).

[martinjrobins]

Thanks @Armavica, the API docs can certainly use some attention. I've added docstrings to all (I think!) the publically exported API. There is a lot in diffsol that would only be of use to advanced users, and I've tried to summarise all the most important structs and traits at the top of the lib.rs file so its right there when you go to the docs.rs page. I've also added module-level docs on the same page in the section you have indicated, I didn't realise you could do this and it looks nice :)

There are some structs related to stochastic equations (like OdeEquationsStoch) which while they are publically exported they are not really useful yet since I've not written any stochastic solvers, so I've not documented these for now as they will probably change

This is all done in #229, have a look and see if it covers everything you think is missing

[Armavica]

Thank you for the extensive documentation! If I am not mistaken some is still missing, notably for the op closures (but I am not sure how useful that is).

Thank you also for the module-level documentation, it is helpful! Both methods work, so it's your choice, but I think I usually see it as //! comments at the top of the relevant mod.rs file, instead of as /// comments on the pub mod lines, because this improves the locality of the documentation and the code that it documents. This also allows, if you add //! comments to the top of submodule files (for example ode_solver/problem.rs), to fill the submodule sections. Feel free to add them to places where you think it would be nice (or not, if you think that things are sufficiently well documented elsewhere)

[martinjrobins]

hmmm, I tried this in #236

I'm not sure I like it though. The links are much more messy in the mod.rs files since I've designed it so that all the structs/traits are re-exported from the crate root. Plus before you could just read through the one file (lib.rs) to get a good overview of the structure.

I'm leaning towards keeping the high-level module docstrings in the lib.rs. For submodules e.g. ode_solver/problem.rs I agree that these should be local.

[martinjrobins]

I think this can be closed now, if there is anything remaining please re-open @Armavica