Documentation

[evaenns]

Documentation of openmpp functions could be improved. Currently it is quite terse. Perhaps it is relying on an understand of OpenM++ nomenclature, but to function as a standalone R package, more plain text description of functions (including as they related to OpenM++ functionality is needed). Many documentation files also include a long list of usage examples, but do not describe what these different uses do. e.g.
https://github.com/mattwarkentin/openmpp/blob/1e62533966619e9641658096395bf607f2d2e050/man/get_workset.Rd#L25C1-L62C40

Part of: openjournals/joss-reviews#7435

[mattwarkentin]

Documentation of openmpp functions could be improved. Currently it is quite terse.

Many/most of the functions exported by this package are very low-level API endpoints that the vast majority of users won't/shouldn't use directly. But we do export them for completeness. Those who seek to use these functions will likely be more expert.

The main classes (OpenMppModel, OpenMppWorkset, OpenMppModelRun, OpenMppModelRunSet) and commonly-used functions (e.g., load_model(), etc.) are documented fairly extensively.

Many documentation files also include a long list of usage examples, but do not describe what these different uses do. e.g.

These files which contain many usage examples are the low-level functions described above that we don't really expect most users will ever need to use directly. We believe that those users that seek to use these functions directly will have an expert understanding of when and how to use them.

However, to improve the ability for users to understand these low-level functions, we have updated all of our documentation to include links to the source documentation for these API endpoints. For example:

openmpp/R/oms-Administrative.R

Lines 1 to 4 in 8774311

	#' OpenM++ Administrative Tasks
	#'
	#' Functions for performing administrative tasks. More information about the
	#' administrative API endpoints can be found at [here](https://github.com/openmpp/openmpp.github.io/wiki/Oms-web-service-API#administrative-manage-web-service-state).