4 Documentation and Examples

We use roxygen for documentation and examples. Some advice follows,

  • The title will probably be something like “Bayesian model of awesomeness”.
  • Following the title you should add a description of the model. Some things to consider are,
    • What is the model?
    • What are the equation(s) of the model (if it is not already obvious and if they can be stated clearly)?
    • On what parameters can the user specify priors?
  • Don’t forget to export the function with @export.
  • Where possible, always use @template (and, if relevant, @tamplateVar) to pull in the existing templates from the man-roxygen folder.
  • Document the additional arguments that are not covered by the templates using @param
  • In @seealso,
    • Point the user to the rstanarm vignettes associated with the model.
    • Mention related models (especially if you’re implementing multiple models from a single package).
  • In @details specify,
    • The R package being emulated.
    • What is being done “under-the-hood” at a high-level.
    • What .fit file the model calls.

Note, every time you make a change to the documentation you need to rebuild the documentation (e.g. run devtools::document()) to make sure it works. If you want to check that links to other packages work then you’ll have to rebuild the package (e.g. run devtools::build()).