vertesy / roxygenready

Prepare your R function library to be compiled into an R package by Roxygen

Create Roxygen skeletons for all of your functions before compiling it into an R package.

Roxygen2 is an awesome tool to easily create a package from your function library.

RoxygenReady helps in creating the function annotations needed to compile a proper package by Roxygen2.

More precisely, RoxygenReady creates Roxygen skeletons, a certain format for inline function annotation (see below). By so, it spares you a lot of time documenting your functions easily and precisely.

The annotation skeleton it creates, can be automatically compiled into a package with a few lines of code. Packages are the standard way of distribution R code, as they integrate with other services, code sharing becomes much easier. See the installation section for an example.

You can pass a whole file to RoxygenReady, and it will create Roxygen skeletons for all functions defined in the file!

Installation and Usage

1. Install directly from GitHub via devtools with one R command:

   devtools::install_github(repo = "vertesy/RoxygenReady/RoxygenReady")

2. ...then simply load the package:

   require("RoxygenReady")

3. and create Roxygen skeletons for your functions

   RoxygenReady("Path/to/your/script.r")

Workflow Explained: a streamlined package creation

1. You start out with your .R file containing your favorite functions.

 		print11more <- function(n=1, m=1) { # a function with real added value
			print (n+(11*m))
		}

- RoxygenReady expects a short description in the first line, after the `{` character, which will be parsed into the description field of the function annotation.

2. Construct Roxygen skeletons RoxygenReady from all functions in your script.

		#' print11more
		#'
		#' # a function with real added value
		#' @param n
		#' @param m
		#' @examples print11more(n=1, m=1)
		#' @export


		print11more <- function(n=1, m=1) {
			print (n+(11*m))
		}

3. Compile your package by roxygen.

- See section: **How to create an R package?**

4. Installing your package and share via GitHub!

    install.packages("YourPackage")
    require("YourPackage")

Browse for help on your functions help(print11more):

You can share your package on GitHub, and everyone can super easily install it, like this package: read on!

Package content

A couple of functions to generate inline description from your functions, using their names and arguments as default input. These can be later parsed by Roxygen to an R package's help section.

1. Check out the list of functions
2. Browse the code of the functions

How to create an R package?

check: Workflow_to_Create_an_R_Package.R for details

1. Write or collect your favorite functions into an R script.

• Prepare in-line documentation with RoxygenReady
• Create a new package by roxygen2's create() function, copy your functions script.
• Explain parameters in the in-line annotation; manually :-(
• Compile a package & documentation by roxygen2
• Install your package locally
• Test your package
• Share it with others via GitHub

Examples

1. Go through the example scripts to understand how the package works.

• You can also check Workflow_to_Create_an_R_Package.R for more details

• And maybe check out a great introduction about writing your first package in R by Hillary Parker

**RoxygenReady** is a project of @vertesy.

edit the website

roxygenready's Issues

Small updates

• Add a header, "Created by RR",
• Search Stack overflow / Set up an alert for keyword
• Webpage: Install and usage / workflow explained,
• Webpage: "from" missing
• Release 1.0.1

Annotate some missing parameters

Edit the project's own website to redirect to vertesy/RoxygenReady

Do it at the very end, it will be overwritten every time you load Readme.md

change the following links

• view on github
• maintained by
• edit the website?

edit:

   subl /Users/abelvertesy/roxygenready.github.io/index.html

Add description comment handling to descriptor_roxy() function

First line comment is parsed to the description field of the roxygen-ready annotation (3rd line)

Unquoting of path parameters in example breaks check

fct(dir = "/path/to/file", ...)

becomes

#' @examples fct(dir = /path/to/file, ...)

Rename core function to .FileToFile / .MemoryToFile / .MemoryToClipboard

Rephrase as Roxygen Skeleton

Refer to RStudio's single function feature

https://stackoverflow.com/questions/10825058/can-rstudio-automatically-generate-an-roxygen-template-for-a-function?rq=1

Also refer to

https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html

Create a function to parse the Function_Overview.md page in the wiki

RoxygenReady.MemoryToClipboard has 3 bugs, and missing a feature

1. Bugs
   • The header line and
   • the @example and
   • the Description lines are incorrect !

instead of

   #' RoxygenReady.MemoryToClipboard 

it should be:

   #' Your functions

• ### missing feature: It should also parse the function's body to the clipboard

rr_extract_all_functions_from_a_script expects `<-`

Although I know it's not the coding standard, I use = for assignment in R, and this includes function defintion. I see that rr_extract_all_functions_from_a_script is grepping as follows:
patt = " *<- *function *\\(.+"
index = grep(patt, ScriptAsStringsPerLine, perl = T)

This results in RoxygenReady not detecting any functions in my script.

could not find function "as.named.vector"

This is a useful premise for a package. Running on a sample script I find:

Error in rr_extract_default_args(funnames[i]) :
could not find function "as.named.vector"

Looking in another repo I see: https://github.com/vertesy/TheCorvinas/blob/master/R/CodeAndRoll.R#L186

as.named.vector <- function(df_col, WhichDimNames = 1) { # Convert a dataframe column or row into a vector, keeping the corresponding dimension name.
    # use RowNames: WhichDimNames = 1 , 2: use ColNames
    # !!! might require drop=F in subsetting!!! eg: df_col[,3, drop=F]
    # df_col[which(unlist(lapply(df_col, is.null)))] = "NULL" # replace NULLs - they would fall out of vectors - DOES not work yet
    namez = dimnames(df_col)[[WhichDimNames]]
    if (is.list(df_col) & !is.data.frame(df_col)) {namez = names(df_col)}
    vecc = as.vector(unlist (df_col))
    names (vecc)= namez
    return (vecc)
}

Sourcing the above function allows the code to run without error.

Before / After Scripts as an example

object ' FUN' not found

Constantly getting Error in FUN(X[[i]], ...) : object ' FUN' not found in almost all files.

Make the package idependent of other functions

& Learn about package testing...

• Take the functions from CodeAndRoll

Comments extraction from multiline argment lists is not working

Neither in RoxygenReady(), nor in rr_ ... overview function..

wrong regex

in rr_extract_all_functions_from_a_script the regex needs to be:
patt = " *(<-|=) *function *\\(.+"
instead of:
patt = " *<-|= *function *\\(.+"

or you will grep other (non-function) lines.