Adding Sinew to Roxygen Skeletons

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"

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