News

Adding Sinew to Roxygen Skeletons

Posted by Yoni Sidi on May 31, 2017 3:52:45 PM

For new developers, getting a package ready for building and submitting to CRAN is an expletive-filled, head-scratching experience to say the least. Trying to figure out the basics of what goes in depends and what goes in imports is a lost afternoon most of us would like back. Once that is understood, filling in relevant information to each field is a mundane task even for a well polished package developer. The out-of-the-box roxygen skeleton supplied by RStudio gives the bare bones road map of what should be part of function documentation:

#stats::lm skeleton example

#' Title
#'
#' @param formula 
#' @param data 
#' @param subset 
#' @param weights 
#' @param na.action 
#' @param method 
#' @param model 
#' @param x 
#' @param y 
#' @param qr 
#' @param singular.ok 
#' @param contrasts 
#' @param offset 
#' @param ... 
#'
#' @return
#' @export
#'
#' @examples

There is a lot of heavy lifting still left to do: 

  • Are there default values for the parameter?
  • What namespaces are used in the function that need to be imported?
  • What are the best candidates for seealso links?
  • Should other roxygen fields be used to make better documentation?

Sinew is a R package that generates a roxygen skeletons populated with information scraped from within the function script.

The goal of the package is to automate nearly all of the mundane tasks needed to document functions, properly set up the import fields for oxygenation, and make it easier to attain documentation consistency across functions. 

Package Functionality

  • makeOxygen: Create a skeleton for roxygen documentation populated with information scraped from within the package function scripts.
  • makeImport: Create import calls for DESCRIPTION, NAMESPACE, and roxygen.
  • makeDictionary: Create a R file of all the unique roxygen parameter fields in a package R subdirectory.

 Installation

#CRAN
install.packages('sinew')

#DEV
devtools::install_github('metrumresearchgroup/sinew')

makeOxygen

Function that returns the skeleton for roxygen documentation including title, description, return, import, and other fields populated with information scraped from the function script.

Basic Usage

makeOxygen is the main function in the package. Running the default setting returns a skeleton with minimal required fields to run devtools::check(build_args = '--as-cran'): title, description, param, and return.

Adding Some Meat to the Bones…

The added value of sinew is that it scrapes the script and fills in many important holes in the documentation:

  • param default values:
    • If a default value is set for a function parameter it will be added to the end @param line.
  • import/importFrom
    • It is assumed that the developer is abiding by the CRAN rules and uses the proper namespace syntax package::function when calling functions in the script. The package scrapes the script with makeImport to create the valid calls for @import and @importFrom which are placed at the bottom of the output. The user has control over the number of functions that are listed in importFrom package function1 [ function2 ...] until only @import package is returned (more below).
  • seealso
    • Linking to other packages is also taken care of when adding the field @seealso. Any functions that are included in @importFrom will have a link to them by default.

Examples showing different parameter specification in makeOxygen

Basic

makeOxygen(lm)
#' @title FUNCTION_TITLE
#' @description FUNCTION_DESCRIPTION
#' @param formula PARAM_DESCRIPTION
#' @param data PARAM_DESCRIPTION
#' @param subset PARAM_DESCRIPTION
#' @param weights PARAM_DESCRIPTION
#' @param na.action PARAM_DESCRIPTION
#' @param method PARAM_DESCRIPTION, Default: 'qr'
#' @param model PARAM_DESCRIPTION, Default: TRUE
#' @param x PARAM_DESCRIPTION, Default: FALSE
#' @param y PARAM_DESCRIPTION, Default: FALSE
#' @param qr PARAM_DESCRIPTION, Default: TRUE
#' @param singular.ok PARAM_DESCRIPTION, Default: TRUE
#' @param contrasts PARAM_DESCRIPTION, Default: NULL
#' @param offset PARAM_DESCRIPTION
#' @param ... PARAM_DESCRIPTION
#' @return OUTPUT_DESCRIPTION
#' @importFrom stats model.frame

Add_fields

Control over which roxygen fields are added to the header is passed through add_fields.

makeOxygen(colourpicker:::colourPickerGadget,add_fields = c('export','details','examples'))
#' @title FUNCTION_TITLE
#' @description FUNCTION_DESCRIPTION
#' @param numCols PARAM_DESCRIPTION, Default: 3
#' @return OUTPUT_DESCRIPTION
#' @export
#' @details DETAILS
#' @examples
#' EXAMPLE1 
#' @importFrom colourpicker colourInput updateColourInput
#' @importFrom grDevices colours
#' @importFrom shiny addResourcePath dialogViewer runGadget shinyApp
#' @importFrom shinyjs useShinyjs extendShinyjs toggleState disable onclick alert
#' @importFrom utils packageVersion

Cut

Passing cut to makeOxygen to return import package instead of importFrom package function1 [function2 ...] for packages that call more than the value assigned to cut.

> makeOxygen(colourpicker:::colourPickerGadget,add_fields = c('export','details','examples'),cut=3)
#' @title FUNCTION_TITLE
#' @description FUNCTION_DESCRIPTION
#' @param numCols PARAM_DESCRIPTION, Default: 3
#' @return OUTPUT_DESCRIPTION
#' @export
#' @details DETAILS
#' @examples
#' EXAMPLE1 
#' @importFrom colourpicker colourInput updateColourInput
#' @importFrom grDevices colours
#' @import shiny
#' @import shinyjs
#' @importFrom utils packageVersion

Seealso

When calling addfields('seealso') the function will guess which functions to add conditional (?) on the value cut it is set to. That is, any function returned with importFrom will also have a seealso link created for it.

> makeOxygen(shinyHeatmaply:::heatmaplyGadget,cut=3,add_fields = 'seealso')
#' @title FUNCTION_TITLE
#' @description FUNCTION_DESCRIPTION
#' @param obj PARAM_DESCRIPTION
#' @param plotHeight PARAM_DESCRIPTION, Default: 800
#' @param viewerType PARAM_DESCRIPTION, Default: 'paneViewer'
#' @param ... PARAM_DESCRIPTION
#' @return OUTPUT_DESCRIPTION
#' @seealso
#'  \code{\link[DT]{dataTableOutput}},\code{\link[DT]{renderDataTable}}
#'  \code{\link[tools]{file_path_sans_ext}}
#'  \code{\link[xtable]{xtable}}
#' @importFrom DT dataTableOutput renderDataTable
#' @import heatmaply
#' @import htmltools
#' @import plotly
#' @import shiny
#' @import stats
#' @importFrom tools file_path_sans_ext
#' @importFrom xtable xtable

Dictionary

A dictionary is a R file produced with makeDictionary. This R file contains all the unique roxygen parameter fields in a package R subdirectory. makeOxygen uses the parameter in the dictionary and, if found, it returns the dictionary entry instead of the default output (more details at the end of the post...).

makeOxygen(sinew::tabular,add_fields = c('examples','export'))

#' @title FUNCTION_TITLE
#' @description FUNCTION_DESCRIPTION
#' @param df PARAM_DESCRIPTION
#' @param header PARAM_DESCRIPTION, Default: TRUE
#' @param ... PARAM_DESCRIPTION
#' @return OUTPUT_DESCRIPTION
#' @examples 
#' EXAMPLE1 
#'
#' @export 

dict_loc='https://raw.githubusercontent.com/metrumresearchgroup/sinew/master/man-roxygen/Dictionary-1.R'

makeOxygen(sinew::tabular,use_dictionary = dict_loc,add_fields = c('examples','export'))

#' @title FUNCTION_TITLE
#' @description FUNCTION_DESCRIPTION
#' @param df data.frame to convert to table
#' @param header boolean to control if header is created from names(df), Default: TRUE
#' @param ...
#' @return OUTPUT_DESCRIPTION
#' @examples 
#' EXAMPLE1 
#'
#' @export

Data.frames

makeOxygen also creates documentation for data.frames and tibble objects

makeOxygen(iris)
#' @title DATASET_TITLE
#' @description DATASET_DESCRIPTION
#' @format A data frame with 150 rows and 5 variables:
#' \describe{
#'   \item{\code{Sepal.Length}}{double COLUMN_DESCRIPTION}
#'   \item{\code{Sepal.Width}}{double COLUMN_DESCRIPTION}
#'   \item{\code{Petal.Length}}{double COLUMN_DESCRIPTION}
#'   \item{\code{Petal.Width}}{double COLUMN_DESCRIPTION}
#'   \item{\code{Species}}{integer COLUMN_DESCRIPTION} 
#'}
"iris"

makeImport

When building a package to submit to CRAN, you need to have namespace calls for any function that is being imported. It is a pain to manually parse through the code looking for all the *::* and writing it in the roxygen header. This function does that for you.

You can write your scriptnormally with the namespace calls and in the end run the function and you can paste the output into the header (or use it as part of makeOxygen).

The function is written to work on single files or whole directories, like a package R subdirectory.

The output can be set to return the format needed for either an roxygen header, NAMESPACE or the DESCRIPTION.

DESCRIPTION

makeImport(script=list.files('R',full.names = T),print = T,format = 'description')
Imports: rstudioapi,utils

NAMESPACE

makeImport(script=list.files('R',full.names = T),print = T,format = 'namespace')
 
importFrom(rstudioapi,getActiveDocumentContext)
importFrom(rstudioapi,insertText)
importFrom(utils,installed.packages)

roxygen

makeImport(script=list.files('R',full.names = T),print = T,format = 'oxygen')
 
R/importAddin.R
#' @importFrom rstudioapi getActiveDocumentContext
 
R/makeImport.R
#' @importFrom utils installed.packages
 
R/makeOxygen.R

 
R/makeSeeAlso.R

 
R/oxygenAddin.R
#' @importFrom rstudioapi getActiveDocumentContext insertText

importFrom cutoff

Setting cut to a value allows for the control over how many functions to list in a package before concatenating the importFrom to an import. This is useful when there are many functions being used throughout the package from the same library and it is practically the same as just importing the whole library

makeImport(script='R/oxygenAddin.R',print = T,format = 'oxygen')

R/oxygenAddin.R
#' @importFrom rstudioapi getActiveDocumentContext insertText
 
makeImport(script='R/oxygenAddin.R',print = T,format = 'oxygen',cut=2)
 
R/oxygenAddin.R
#' @import rstudioapi

makeDictionary

This function takes the idea of roxygen templates, but repurposes their use. It creates an R file of all the unique roxygen parameter fields in a package R subdirectory. This serves a few functions:

  • Creates a general template for regular use with roxygen,
  • Provides a simple way to check that there are no redundant parameter descriptions and that they are consistent,
  • When present, this is used internally with ls_param to call parameter descriptions in bulk from a centralized template to populate makeOxygen skeletons.

For example in the man-roxygen there is a Dictionary-1.R file that was created by makeDictionary. Using ls_param a query is run on the dictionary to return the param fields that intersect with the formals call to the functions.

dict_loc='https://raw.githubusercontent.com/metrumresearchgroup/sinew/master/man-roxygen/Dictionary-1.R'

ls_param(sinew::makeOxygen,dictionary = dict_loc)

#' @param obj function or name of function
#' @param add_default boolean to add defaults values to the end of the PARAM fields, Default: TRUE
#' @param add_fields character vector to add additional roxygen fields, Default: NULL
#' @param print boolean print output to console, Default: TRUE
#' @param ... 

names(formals(makeOxygen))
[1] "obj"         "add_default" "add_fields"  "print"       "..."

 

Jonathan Sidi joined Metrum Research Group in 2016 after working for several years on problems in applied statistics, financial stress testing, and economic forecasting in both industrial and academic settings. To learn more about additional open-source software packages developed by Metrum Research Group please visit the Metrum website. Contact: For questions and comments, feel free to email me at: yonis@metrumrg.com or open an issue for bug fixes or enhancements at github.

Topics: Methodology, Tools, and Computation

We love to share!

Please take advantage of the content we provide here. Our goal is to help, encourge, and inspire you in your own work! If you have suggestions for blog topics, or would like to co-author a blog post with us, let us know!

Posts by Topic

see all

Subscribe to Email Updates

Recent Posts

Privacy  |  2020 Metrum Research Group