<p><div><div><div><div data-show-faces="false" data-height="21" data-width="100" data-layout="button_count" data-send="true" data-href="https://www.r-bloggers.com/rstudioaddins-part-2-roxygen-documentation-formatting-made-easy/"></div></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/"> Jozef's Rblog</a></strong>, and kindly contributed to <a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers)</a> </div>
<div>
<h1>Introduction</h1>
<p>Code documentation is extremely important if you want to share the code with anyone else, future you included. In this second post in the RStudio:addins series we will pay a part of our technical debt from the <a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r101-addin-reproducibility" target="_blank">previous article</a> and document our R functions conveniently using a new addin we will build for this purpose.</p>
<blockquote>
<h4>The addin we will create in this article will let us create well formatted roxygen documentation easily by using keyboard shortcuts to add useful tags such as <code>\code{}</code> or <code>\link{}</code> around selected text in RStudio.</h4>
</blockquote>
</div>
<div>
<h1>Contents</h1>
<ol>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#quick-intro-to-documentation-with-roxygen2" target="_blank">Quick intro to documentation with roxygen2</a>
<ol>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#documenting-your-first-function" target="_blank">Documenting your first function</a></li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#generating-and-viewing-the-documentation" target="_blank">Generating and viewing the documentation</a></li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#a-real-life-example" target="_blank">Real-life example</a></li>
</ol>
</li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#our-addins-to-make-documenting-a-breeze" target="_blank">Our addins to make documenting a breeze</a>
<ol>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#add-a-selected-tag-around-a-character-string" target="_blank">Add a selected tag around a character string</a></li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#apply-the-tag-on-a-selection-in-an-active-document-in-rstudio" target="_blank">Apply the tag on a selection in an active document in RStudio</a></li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#wrappers-around-addroxytag-to-be-used-as-addin-for-some-useful-tags" target="_blank">Wrappers around <code>addRoxytag</code> to be used as addin for some useful tags</a></li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#add-the-addin-bindings-into-addins.dcf-and-assign-keyboard-shortcuts" target="_blank">Add the addin bindings into <code>addins.dcf</code> and assign keyboard shortcuts</a></li>
</ol>
</li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#the-addins-in-action" target="_blank">The addins in action</a></li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#what-is-next---even-more-automated-documentation" target="_blank">What is next – even more automated documentation</a></li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#tldr---just-give-me-the-package" target="_blank">TL;DR – Just give me the package</a></li>
<li><a rel="nofollow" href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/#references" target="_blank">References</a></li>
</ol>
</div>
<div>
<h1>Quick intro to documentation with roxygen2</h1>
<div>
<h2>1. Documenting your first function</h2>
<p>To help us generate documentation easily we will be using the <a rel="nofollow" href="https://cran.r-project.org/web/packages/roxygen2/vignettes/roxygen2.html" target="_blank">roxygen2</a> package. You can install it using <code>install.packages(&quot;roxygen2&quot;)</code>. Roxygen2 works with in-code tags and will generate R’s documentation format <code>.Rd</code> files, create a <code>NAMESPACE</code>, and manage the <code>Collate</code> field in <code>DESCRIPTION</code> (not relevant to us at this point) automatically for our package.</p>
<p>Documenting a function works in 2 simple steps:</p>
<div>
<img alt="Documenting a function" src="https://i1.wp.com/jozefhajnala.gitlab.io/r/img/r102-01-add-roxy-skeleton.gif?w=456&ssl=1" data-recalc-dims="1">
<p>Documenting a function</p>
</div>
<ol>
<li>Inserting a skeleton – Do this by placing your cursor anywhere in the function you want to document and click <code>Code Tools -> Insert Roxygen Skeleton</code> (default keyboard shortcut <code>Ctrl+Shift+Alt+R</code>).</li>
<li>Populating the skeleton with relevant information. A few important tags are:</li>
</ol>
<ul>
<li><code>#' @params</code> – describing the arguments of the function</li>
<li><code>#' @return</code> – describing what the function returns</li>
<li><code>#' @importFrom package function</code> – in case your function uses a function from a different package Roxygen will automatically add it to the <code>NAMESPACE</code></li>
<li><code>#' @export</code> – if case you want the function to be exported (mainly for use by other packages)</li>
<li><code>#' @examples</code> – showing how to use the function in practice</li>
</ul>
</div>
<div>
<h2>2. Generating and viewing the documentation</h2>
<div>
<img alt="Generating and viewing the documentation" src="https://i0.wp.com/jozefhajnala.gitlab.io/r/img/r102-02-generate-doc.gif?w=456&ssl=1" data-recalc-dims="1">
<p>Generating and viewing the documentation</p>
</div>
<ol>
<li>We generate the documentation files using <code>roxygen2::roxygenise()</code> or <code>devtools::document()</code> (default keyboard shortcut <code>Ctrl+Shift+D</code>)</li>
<li>Re-installing the package (default keyboard shortcut <code>Ctrl+Shift+B</code>)</li>
<li>Viewing the documentation for a function using <code>?functioname</code> e.g. <code>?mean</code>, or placing cursor on a function name and pressing <code>F1</code> in RStudio – this will open the <code>Viewer</code> pane with the help for that function</li>
</ol>
</div>
<div>
<h2>3. A real-life example</h2>
<p>Let us now document <code>runCurrentRscript</code> a little bit:</p>
<pre><code>#' runCurrentRscript
#' @description Wrapper around executeCmd with default arguments for easy use as an RStudio addin
#' @param path character(1) string, specifying the path of the file to be used as Rscript argument (ideally a path to an R script)
#' @param outputFile character(1) string, specifying the name of the file, into which the output produced by running the Rscript will be written
#' @param suffix character(1) string, specifying additional suffix to pass to the command
#' @importFrom rstudioapi getActiveDocumentContext
#' @importFrom rstudioapi navigateToFile
#' @seealso executeCmd
#' @return side-effects
runCurrentRscript &lt;- function(
  path = replaceTilde(rstudioapi::getActiveDocumentContext()[[&quot;path&quot;]])
, outputFile = &quot;output.txt&quot;
, suffix = &quot;2>&amp;1&quot;) {
  cmd &lt;- makeCmd(path, outputFile = outputFile, suffix = suffix)
  executeCmd(cmd)
  if (!is.null(outputFile) &amp;&amp; file.exists(outputFile)) {
    rstudioapi::navigateToFile(outputFile)
  }
}</code></pre>
<p>As we can see by looking at <code>?runCurrentRscript</code> versus <code>?mean</code>, our documentation does not quite look up to par with documentation for other functions: <img alt="comparing the view of documentation for base::mean and runCurrentRscript" src="https://i1.wp.com/jozefhajnala.gitlab.io/r/img/r102-03-compare.png?w=456&ssl=1" data-recalc-dims="1"></p>
<p>What is missing if we abstract from the richness of the content is the usage of markup commands (tags) for formatting and linking our documentation. Some of the very useful such tags are for example:</p>
<ul>
<li><code>\code{}</code>, <code>\strong{}</code>, <code>\emph{}</code> for font style</li>
<li><code>\link{}</code>, <code>\href{}</code>, <code>\url{}</code> for linking to other parts of the documentation or external resources</li>
<li><code>\enumerate{}</code>, <code>\itemize{}</code>, <code>\tabular{}</code> for using lists and tables</li>
<li><code>\eqn{}</code>, <code>\deqn{}</code> for mathematical expressions such as equations etc.</li>
</ul>
<blockquote>
<p>For the full list of options regarding text formatting, linking and more see <a rel="nofollow" href="https://cran.r-project.org/doc/manuals/R-exts.html#Rd-format" target="_blank">Writing R Extensions’ Rd format chapter</a></p>
</blockquote>
</div>
</div>
<div>
<h1>Our addins to make documenting a breeze</h1>
<p>As you can imagine, typing the markup commands in full all the time is quite tedious. The goal of our new addin will therefore be to make this process efficient using keyboard shortcuts – just select a text and our addin will place the desired tags around it. For this time, we will be satisfied with simple 1 line tags.</p>
<div>
<h2>1. Add a selected tag around a character string</h2>
<pre><code>roxyfy &lt;- function(str, tag = NULL, splitLines = TRUE) {
  if (is.null(tag)) {
    return(str)
  }
  if (!isTRUE(splitLines)) {
    return(paste0(&quot;\\&quot;, tag, &quot;{&quot;, str, &quot;}&quot;))
  }
  str &lt;- unlist(strsplit(str, &quot;\n&quot;))
  str &lt;- paste0(&quot;\\&quot;, tag, &quot;{&quot;, str, &quot;}&quot;)
  paste(str, collapse = &quot;\n&quot;)
}</code></pre>
</div>
<div>
<h2>2. Apply the tag on a selection in an active document in RStudio</h2>
<p>We will make the functionality available for multi-selections as well by <code>lapply-ing</code> over the <code>selection</code> elements retrieved from the active document in RStudio.</p>
<pre><code>addRoxytag &lt;- function(tag = NULL) {
  context &lt;- rstudioapi::getActiveDocumentContext()
  lapply(X = context[[&quot;selection&quot;]]
       , FUN = function(thisSel, contextid) {
           rstudioapi::modifyRange(location = thisSel[[&quot;range&quot;]]
                                 , roxyfy(thisSel[[&quot;text&quot;]], tag)
                                 , id = contextid)
         }
       , contextid = context[[&quot;id&quot;]]
       )
  return(invisible(NULL))
}</code></pre>
</div>
<div>
<h2>3. Wrappers around <code>addRoxytag</code> to be used as addin for some useful tags</h2>
<pre><code>addRoxytagCode &lt;- function() {
  addRoxytag(tag = &quot;code&quot;)
}

addRoxytagLink &lt;- function() {
  addRoxytag(tag = &quot;link&quot;)
}

addRoxytagEqn &lt;- function() {
  addRoxytag(tag = &quot;eqn&quot;)
}</code></pre>
</div>
<div>
<h2>4. Add the addin bindings into <code>addins.dcf</code> and assign keyboard shortcuts</h2>
<p>As the final step, we need to add the bindings for our new addins to the <code>inst/rstudio/addins.dcf</code> file and re-install the package.</p>
<pre><code>Name: addRoxytagCode
Description: Adds roxgen tag code to current selections in the active RStudio document
Binding: addRoxytagCode
Interactive: false

Name: addRoxytagLink
Description: Adds roxgen tag link to current selections in the active RStudio document
Binding: addRoxytagLink
Interactive: false

Name: addRoxytagEqn
Description: Adds roxgen tag eqn to current selections in the active RStudio document
Binding: addRoxytagEqn
Interactive: false</code></pre>
<div>
<img alt="assigning keyboard shortcuts to addins" src="https://i0.wp.com/jozefhajnala.gitlab.io/r/img/r102-04-assign-shortcuts.gif?w=456&ssl=1" data-recalc-dims="1">
<p>assigning keyboard shortcuts to addins</p>
</div>
</div>
</div>
<div>
<h1>The addins in action</h1>
<p>And now, let’s just select the text we want to format and watch our addins do the work for us! Then document the package, re-install it and view the improved help for our functions:</p>
<div>
<img alt="The addins in action" src="https://i1.wp.com/jozefhajnala.gitlab.io/r/img/r102-05-addins-in-action.gif?w=456&ssl=1" data-recalc-dims="1">
<p>The addins in action</p>
</div>
</div>
<div>
<h1>What is next – even more automated documentation</h1>
<p>Next time we will try to enrich our addins for generating documentation by adding the following functionalities</p>
<ul>
<li>automatic generation of <code>@importFrom</code> tags by inspecting the function code</li>
<li>allowing for more complex tags such as <code>itemize</code></li>
</ul>
</div>
<div>
<h1>TL;DR – Just give me the package</h1>
<ul>
<li>Get the <a rel="nofollow" href="https://gitlab.com/jozefhajnala/jhaddins/tags/addins2-roxytagsMadeFast" target="_blank">status of the package after this article</a></li>
<li>or use <code>git clone</code> from <a rel="nofollow" href="https://gitlab.com/jozefhajnala/jhaddins.git" target="_blank"><code>https://gitlab.com/jozefhajnala/jhaddins.git</code></a></li>
</ul>
</div>
<div>
<h1>References</h1>
<ul>
<li><a rel="nofollow" href="https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html" target="_blank">Generating Rd files</a> with Roxygen2</li>
<li><a rel="nofollow" href="https://cran.r-project.org/web/packages/roxygen2/vignettes/formatting.html" target="_blank">Formatting reference sheet</a></li>
<li><a rel="nofollow" href="https://cran.r-project.org/doc/manuals/R-exts.html#Rd-format" target="_blank">Writing R Extensions – Rd format</a></li>
</ul>
</div>
	<p>
<div>
<div>To <strong>leave a comment</strong> for the author, please follow the link and comment on their blog: <strong><a href="https://jozefhajnala.gitlab.io/r/r102-addin-roxytags/"> Jozef's Rblog</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 rel="nofollow" href="https://www.r-project.org/" title="The R Project for Statistical Computing">R</a> news and <a rel="nofollow" href="https://www.r-bloggers.com/search/tutorial" title="R tutorials">tutorials</a> on topics such as: <a rel="nofollow" href="https://www.r-bloggers.com/search/data%20science" title="Data science">Data science</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/Big%20Data" title="Big Data">Big Data, <a rel="nofollow" href="https://www.r-users.com/" title="R jobs">R jobs</a>, visualization (<a rel="nofollow" href="https://www.r-bloggers.com/search/ggplot2" title="ggplot and ggplot2 tutorials">ggplot2</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/boxplot" title="Boxplots using lattice and ggplot2 tutorials">Boxplots</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/map" title="Maps and gis">maps</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/animation" title="Animation in R">animation</a>), programming (<a rel="nofollow" href="https://www.r-bloggers.com/search/RStudio" title="RStudio IDE for R">RStudio</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/sweave" title="Sweave and literate programming">Sweave</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/LaTeX" title="LaTeX in R">LaTeX</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/SQL" title="SQL and databases">SQL</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/eclipse" title="Eclipse IDE for R">Eclipse</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/git" title="git and github, Version Control System">git</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/hadoop" title="Large data in R using Hadoop">hadoop</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/Web+Scraping" title="Web Scraping of google, facebook, yahoo, twitter and more using R">Web Scraping</a>) statistics (<a rel="nofollow" href="https://www.r-bloggers.com/search/regression" title="Regressions and ANOVA analysis tutorials">regression</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/PCA" title="principal component analysis tutorial">PCA</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/time+series" title="Time series">time series</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/trading" title="finance trading">trading</a>) and more...
<img width="1" alt="" src="http://feeds.feedburner.com/~r/RBloggers/~4/7fQgVJBNeBI" height="1"></a></div>