<p><div><div><div><div data-width="100" data-show-faces="false" data-send="true" data-layout="button_count" data-height="21" data-href="https://www.r-bloggers.com/sinew-a-r-package-to-create-self-populating-roxygen2-skeletons/"></div></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="http://r-posts.com/adding-sinew-to-roxygen2-skeletons/"> R-posts.com</a></strong>, and kindly contributed to <a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers)</a> </div>
<p><a target="_blank" rel="nofollow" href="https://github.com/metrumresearchgroup/sinew">Sinew</a> is a R package that generates a <a target="_blank" rel="nofollow" href="https://github.com/klutometis/roxygen">roxygen</a>2 skeletons populated with information scraped from within the function script.</p>
<p>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. </p>
<div>
<h2>Functionality</h2>
<ul>
<li><a target="_blank" rel="nofollow" href="https://github.com/metrumresearchgroup/sinew#makeoxygen">makeOxygen</a>: Create a skeleton for roxygen2 documentation populated with information scraped from within the package function scripts.</li>
<li><a target="_blank" rel="nofollow" href="https://github.com/metrumresearchgroup/sinew#makeimport">makeImport</a>: Create import(s) calls for DESCRIPTION, NAMESPACE, and roxygen2.</li>
<li><a target="_blank" rel="nofollow" href="https://github.com/metrumresearchgroup/sinew#makedictionary">makeDictionary</a>: Create a R file of all the unique roxygen2 parameter fields in a package R subdirectory.</li>
</ul>
</div>
<h2>Installation</h2>
<div>
<pre>#CRAN
install.packages('sinew')

#DEV
devtools::install_github('metrumresearchgroup/sinew')</pre>
<h2>Example Output</h2>
<div>
<pre><code>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</code></pre>
</div>
<h2>In more detail…</h2>
<p>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 <em>depends</em> and what goes in <em>imports</em> 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 roxygen2 skeleton supplied by RStudio gives the bare bones road map of what should be part of function documentation:
</div>
<p><span></span></p>
<pre>#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</pre>
<p>There is a lot of heavy lifting still left to do: </p>
<ul>
<li>Are there default values for the parameter?</li>
<li>What namespaces are used in the function that need to be imported?</li>
<li>What are the best candidates for seealso links?</li>
<li>Should other roxygen2 fields be used to make better documentation?</li>
</ul>
<h2>makeOxygen</h2>
<div> </div>
<div>
Function that returns the skeleton for <a target="_blank" rel="nofollow" href="https://github.com/klutometis/roxygen">roxygen</a>2 documentation including title, description, return, import, and other fields populated with information scraped from the function script.
<div>
<h3>Basic Usage</h3>
<p>makeOxygen is the main function in the package. Running the default setting returns a skeleton with minimal required fields to run <code>devtools::check(build_args = '--as-cran')</code>: title, description, param, and return.</p>
<div>
<h4>Adding Some Meat to the Bones…</h4>
<p>The added value of sinew is that it scrapes the script and fills in many important holes in the documentation:</p>
<ul>
<li>param default values:
<ul>
<li>If a default value is set for a function parameter it will be added to the end <code>@param</code> line.</li>
</ul>
</li>
<li>import/importFrom
<ul>
<li>It is assumed that the developer is abiding by the CRAN rules and uses the proper namespace syntax <code>package::function</code> when calling functions in the script. The package scrapes the script with <code>makeImport</code> to create the valid calls for <code>@import</code> and <code>@importFrom</code> which are placed at the bottom of the output. The user has control over the number of functions that are listed in <code>importFrom package function1 [ function2 ...]</code> until only <code>@import package</code> is returned (more below).</li>
</ul>
</li>
<li>seealso
<ul>
<li>Linking to other packages is also taken care of when adding the field <code>@seealso</code>. Any functions that are included in <code>@importFrom</code> will have a link to them by default.</li>
</ul>
</li>
</ul>
<p>Examples showing different parameter specification in makeOxygen
</p>
</div>
<div>
<h4>Basic</h4>
<pre><code>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</code></pre>
</div>
<div>
<h4>Add_fields</h4>
<p>Control over which roxygen2 fields are added to the header is passed through <code>add_fields</code>.</p>
<pre><code>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</code></pre>
</div>
<div>
<h4>Cut</h4>
<p>Passing <code>cut</code> to makeOxygen to return <code>import package</code> instead of <code>importFrom package function1 [function2 ...]</code> for packages that call more than the value assigned to cut.</p>
<pre><code>> 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</code></pre>
</div>
<div>
<h4>Seealso</h4>
<p>When calling <code>addfields('seealso')</code> 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.</p>
<pre><code>> 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
</code></pre>
</div>
<div>
<h4>Dictionary</h4>
<p>A dictionary is a R file produced with <a target="_blank" rel="nofollow" href="https://github.com/metrumresearchgroup/sinew#makedictionary">makeDictionary</a>. This R file contains all the unique roxygen2 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 <a target="_blank" rel="nofollow" href="https://github.com/metrumresearchgroup/sinew#makedictionary">end of the post</a>…).</p>
<pre><code>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 </code></pre>
</div>
<div>
<h4>Data.frames</h4>
<p>makeOxygen also creates documentation for data.frames and tibble objects</p>
<pre><code>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} 
#'}
&quot;iris&quot;</code></pre>
</div>
</div>
</div>
<div>
<h2>makeImport</h2>
<p>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 <code>*::*</code> and writing it in the roxygen2 header. This function does that for you.<br>
You can write your script normally 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 <code>makeOxygen</code>).<br>
The function is written to work on single files or whole directories, like a package R subdirectory.<br>
The output can be set to return the format needed for either an roxygen2 header, NAMESPACE or the DESCRIPTION.</p>
<div>
<h3>DESCRIPTION</h3>
<pre><code>makeImport(script=list.files('R',full.names = T),print = T,format = 'description')
Imports: rstudioapi,utils</code></pre>
</div>
<div>
<h3>NAMESPACE</h3>
<pre><code>makeImport(script=list.files('R',full.names = T),print = T,format = 'namespace')
 
importFrom(rstudioapi,getActiveDocumentContext)
importFrom(rstudioapi,insertText)
importFrom(utils,installed.packages)</code></pre>
</div>
<div>
<h3>roxygen2</h3>
<pre><code>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</code></pre>
<div>
<h4>importFrom cutoff</h4>
<p>Setting cut to a value allows for the control over how many functions to list in a package before concatenating the <code>importFrom</code> to an <code>import</code>. 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</p>
<pre><code>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</code></pre>
</div>
</div>
<div>
<h3>makeDictionary</h3>
<p>This function takes the idea of roxygen2 templates, but repurposes their use. It creates an R file of all the unique roxygen2 parameter fields in a package R subdirectory. This serves a few functions:</p>
<ul>
<li>Creates a general template for regular use with roxygen2,</li>
<li>Provides a simple way to check that there are no redundant parameter descriptions and that they are consistent,</li>
<li>When present, this is used internally with <strong>ls_param</strong> to call parameter descriptions in bulk from a centralized template to populate makeOxygen skeletons.</li>
</ul>
<p>For example in the <a target="_blank" rel="nofollow" href="https://github.com/metrumresearchgroup/sinew/tree/master/man-roxygen">man-roxygen</a> there is a Dictionary-1.R file that was created by <strong>makeDictionary</strong>. Using <strong>ls_param</strong> a query is run on the dictionary to return the param fields that intersect with the formals call to the functions.</p>
<pre><code>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] &quot;obj&quot;         &quot;add_default&quot; &quot;add_fields&quot;  &quot;print&quot;       &quot;...&quot; </code></pre>
<p> 
</p>
</div>
</div>
<hr>
<p><em> 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 <a target="_blank" rel="nofollow" href="http://metrumrg.com/opensourcetools.html">website</a>. Contact: For questions and comments, feel free to email me at: yonis@metrumrg.com or open an issue for bug fixes or enhancements at <a target="_blank" rel="nofollow" href="https://github.com/metrumresearchgroup/sinew/issues">github</a>. </em></p>
<p>
<div>
<div>To <strong>leave a comment</strong> for the author, please follow the link and comment on their blog: <strong><a href="http://r-posts.com/adding-sinew-to-roxygen2-skeletons/"> R-posts.com</a></strong>.</div>
<hr>
<a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers.com</a> offers <strong><a rel="nofollow" href="https://feedburner.google.com/fb/a/mailverify?uri=RBloggers">daily e-mail updates</a></strong> about <a title="The R Project for Statistical Computing" rel="nofollow" href="https://www.r-project.org/">R</a> news and <a title="R tutorials" rel="nofollow" href="https://www.r-bloggers.com/search/tutorial">tutorials</a> on topics such as: <a title="Data science" rel="nofollow" href="https://www.r-bloggers.com/search/data%20science">Data science</a>, <a title="Big Data" rel="nofollow" href="https://www.r-bloggers.com/search/Big%20Data">Big Data, <a title="R jobs" rel="nofollow" href="https://www.r-users.com/">R jobs</a>, visualization (<a title="ggplot and ggplot2 tutorials" rel="nofollow" href="https://www.r-bloggers.com/search/ggplot2">ggplot2</a>, <a title="Boxplots using lattice and ggplot2 tutorials" rel="nofollow" href="https://www.r-bloggers.com/search/boxplot">Boxplots</a>, <a title="Maps and gis" rel="nofollow" href="https://www.r-bloggers.com/search/map">maps</a>, <a title="Animation in R" rel="nofollow" href="https://www.r-bloggers.com/search/animation">animation</a>), programming (<a title="RStudio IDE for R" rel="nofollow" href="https://www.r-bloggers.com/search/RStudio">RStudio</a>, <a title="Sweave and literate programming" rel="nofollow" href="https://www.r-bloggers.com/search/sweave">Sweave</a>, <a title="LaTeX in R" rel="nofollow" href="https://www.r-bloggers.com/search/LaTeX">LaTeX</a>, <a title="SQL and databases" rel="nofollow" href="https://www.r-bloggers.com/search/SQL">SQL</a>, <a title="Eclipse IDE for R" rel="nofollow" href="https://www.r-bloggers.com/search/eclipse">Eclipse</a>, <a title="git and github, Version Control System" rel="nofollow" href="https://www.r-bloggers.com/search/git">git</a>, <a title="Large data in R using Hadoop" rel="nofollow" href="https://www.r-bloggers.com/search/hadoop">hadoop</a>, <a title="Web Scraping of google, facebook, yahoo, twitter and more using R" rel="nofollow" href="https://www.r-bloggers.com/search/Web+Scraping">Web Scraping</a>) statistics (<a title="Regressions and ANOVA analysis tutorials" rel="nofollow" href="https://www.r-bloggers.com/search/regression">regression</a>, <a title="principal component analysis tutorial" rel="nofollow" href="https://www.r-bloggers.com/search/PCA">PCA</a>, <a title="Time series" rel="nofollow" href="https://www.r-bloggers.com/search/time+series">time series</a>, <a title="finance trading" rel="nofollow" href="https://www.r-bloggers.com/search/trading">trading</a>) and more...
<img height="1" alt="" width="1" src="http://feeds.feedburner.com/~r/RBloggers/~4/WFYXyA7BV60"></a></div>