7 Example Data & Documenting Functions

Example Data

One of the most important things in this package is example data from the dataset ex.ptmtable. It is a batch of data files, including the inputs and outputs for functions. All example data begins with "ex." and is stored in the data folder as individual .rda files (or insit directory if it is a non-.rda). It additionally helps if a user wants to view how specific data structures should look.

You can create one of these files yourself by running save after saving your function output:

ex.data <- yourfuncton(ex.param1, ex.param2)
save("ex.data", ex.data, file = data.rda)

Note that is very important that ALL example data created this way is run with other example data. Additionally, example inputs (like the ptmtable) should be cut to a reasonable size so the function runs fast and the data itself does not take up a large amount of storage. This is important because example data is used for both testing and running function examples (see below).

Documenting Functions

Most of the documentation for functions this packages is updated by programs such as roxygen2 when devtools::document() is ran. This can be edited by changing their "Roxygen Skeletons" (Lines that start with #'). These descriptions start with the name of the function OR a very brief line describing what it does. The next lines are a brief description of what it does.

Here's a brief explanation of the flags we commonly use:

• @param Identifies parameters or inputs to a function. It's extremely important, as a pkgdown error can occur if these aren't correct.
• @return Is less important, as our rarely actually return anything (assigns to global environment instead), so this doesn't need to be correct. Regardless, it should still describe the things being assigned to the global environment.
• @exportTells roxygen which function documentations should be displayed on the website's Reference section (sometimes referred to as the package index). There's no good reason to not have this flag.

Examples for Functions

In the above image, you may notice the @examples flag. Anything code below this will be ran whenever roxygen wants to create an example (it will do this at the bottom of the popup created by running ?function. These should use exclusively example data as input, as this prevents us from running the entire pipeline every time we want to show an example. Additionally, you should have it display only a portion of the data, as these data structures are too big to show in their entirety.