{"id":464,"date":"2021-03-02T20:48:45","date_gmt":"2021-03-02T20:48:45","guid":{"rendered":"http:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/?p=464"},"modified":"2021-04-28T09:30:14","modified_gmt":"2021-04-28T09:30:14","slug":"adding-r-package-documentation-rcpp-roxygen2","status":"publish","type":"post","link":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/2021\/03\/02\/adding-r-package-documentation-rcpp-roxygen2\/","title":{"rendered":"Adding R Package Documentation"},"content":{"rendered":"\n

This blog will assume you are able to build a package for R and are comfortable with Linux. Fellow STOR-i student Hamish wrote a blog post on how to do this if you haven’t reached this point yet<\/a>. His post covers how add C++ code to this package also. In this post I will show you how to add documentation for both C++ functions and R functions.<\/em><\/p>\n\n\n\n

At any level of computer programming you may need help. I have worked with R for quite some time now and mainly use RStudio<\/a> for its friendly user interface. Despite this experience I still get stuck, forget what a function does, forget what I need to input into a function for it to work, etc.<\/p>\n\n\n\n

If this happens in R the quickest way to resolve these issues is to use the “help” function. For example, if I forget what “rnorm” does I can type “help(rnorm)” and it will direct me to the documentation telling me all about what it does. What if this documentation didn’t exist?<\/p>\n\n\n\n

I feel that providing documentation for the R packages you make is really important.<\/p>\n\n\n\n

Required Packages<\/h2>\n\n\n\n

To use this tutorial you need both the “Rcpp” package (if you are implementing C++ functions) and “roxygen2” package. In R you can do this using the following code.<\/p>\n\n\n\n

install.packages(Rcpp) # Installs the Rcpp package\ninstall.packages(roxygen2) # Installs the roxygen2 package<\/code><\/pre>\n\n\n\n
The following parts will assume that you have an existing packages skeleton (see Step 1 of Hamish’s blog<\/a>), with either an R function in the “R” folder of the skeleton or a C++ file in the “src” folder.<\/p>\n\n\n\n
First use a text editor of choice to edit the file named “DESCRIPTION”. Simply edit the fields and save. Now navigate into the “man” folder and delete it’s contents, roxygen should generate new documentation files automatically.<\/p>\n\n\n\n
Documentation For R Function<\/h2>\n\n\n\n
To add documentation for an R function open up the folder “R” and find the function you wish to add documentation to. Add the following code above your R function.<\/p>\n\n\n\n
#' Name\n#'\n#' Description\n#' @param variable Parameter_Description\n#' @return Return_Description<\/code><\/pre>\n\n\n\n
Replace “Name” and “Description” with the name of your function and a short description of the function respectively.<\/p>\n\n\n\n
“@param” lets roxygen2 know it should add an argument named “variable” (note the naming needs to be the same as in the function). Replace “Parameter_Description” with a short description of the variable. Each variable of the function needs a line with it’s own details.<\/p>\n\n\n\n
“@return” lets roxygen2 know it should add a “value” section. Replace “Return_Description” with a short description of what the function outputs.<\/p>\n\n\n\n
Documentation For C++ Function<\/h2>\n\n\n\n
To add documentation for a C++ function open up the folder “src” and find the function you wish to add documentation to. Add the following code above your C++ function (and above the [[Rcpp::export]] line).<\/p>\n\n\n\n
\/\/' Name\n\/\/'\n\/\/' Description\n\/\/' @param variable Parameter_Description\n\/\/' @return Return_Description<\/code><\/pre>\n\n\n\n
All of these fields are the same as described in the R function section of this tutorial.<\/p>\n\n\n\n
Building And Installing The Function<\/h2>\n\n\n\n
Navigate into the skeleton folder in a Linux terminal window and start R. You need to run the following code.<\/p>\n\n\n\n
library(Rcpp)\nlibrary(roxygen2)\nRcpp::compileAttributes()           # this updates the Rcpp layer from C++ to R\nroxygen2::roxygenize(roclets=\"rd\")  # this updates the documentation<\/code><\/pre>\n\n\n\n
You can now exit R and move up a folder level using the command “cd ..”<\/p>\n\n\n\n
To build the program run the following terminal command making sure to replace “PackageSkeletonName” with the name of your package skeleton. This will produce a package tarball that you can distribute and install.<\/p>\n\n\n\n
R CMD build PackageSkeletonName<\/code><\/pre>\n\n\n\n
For installation follow Step 3 in Hamish’s blog post<\/a>. <\/p>\n\n\n\n
Example Code<\/h2>\n\n\n\n
The example code contains an algorithm named “Jarvis March” implemented in C++ with documentation that takes a set of 2D points and returns the convex hull, and an R function with documentation that plots the convex hull of a set of 2D points. <\/p>\n\n\n\n
The details of these are not important for the tutorial but instead try to spot where the code in this blog has been used.<\/p>\n\n\n\n
Example code can be found here<\/a><\/p>\n\n\n\n
Further Reading<\/h2>\n\n\n\n
This post written by the authors of Rcpp helped me learn how to add documentation<\/a><\/p>\n\n\n\n
Roxygen2 introduction<\/a><\/p>\n\n\n\n
Rcpp CRAN page<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
This blog will assume you are able to build a package for R and are comfortable with Linux. Fellow STOR-i student Hamish wrote a blog post on how to do this if you haven’t reached this point yet. His post covers how add C++ code to this package also. In this post I will show… Read More »Adding R Package Documentation<\/span><\/a><\/p>\n","protected":false},"author":24,"featured_media":608,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"neve_meta_sidebar":"","neve_meta_container":"","neve_meta_enable_content_width":"","neve_meta_content_width":0,"neve_meta_title_alignment":"","neve_meta_author_avatar":"","neve_post_elements_order":"","neve_meta_disable_header":"","neve_meta_disable_footer":"","neve_meta_disable_title":"","footnotes":""},"categories":[9,2],"tags":[],"class_list":["post-464","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-programming","category-research"],"_links":{"self":[{"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/posts\/464","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/users\/24"}],"replies":[{"embeddable":true,"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/comments?post=464"}],"version-history":[{"count":24,"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/posts\/464\/revisions"}],"predecessor-version":[{"id":615,"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/posts\/464\/revisions\/615"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/media\/608"}],"wp:attachment":[{"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/media?parent=464"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/categories?post=464"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.lancaster.ac.uk\/stor-i-student-sites\/matthew-davison\/wp-json\/wp\/v2\/tags?post=464"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}