devtools roxygen package creation and rd documenta

Question

I am new to roxygen and am struggling to see how to be able to use it to quickly create a new/custom package.

I.e. I would like to know the minimum requirements are to make a package called package1 using devtools, roxygen2/3 so that I can run the commands

require(package1)
fun1(20)
fun2(20)

to generate 2000 and 4000 random normals respectively

So lets take the simplest example.

If I have two functions fun1 and fun2

fun1 <- function(x){
    rnorm(100*x)
}

and

fun2 <- function(y){
    rnorm(200*y)
}

the params are numeric, the return values are numeric. I'm pretty sure this isn't an S3 method, lets call the titles fun1 and fun2....im not too sure what other info i would need to provide. I can put fun1 and fun2 in separate .R files and add abit of #' but am unsure to include all relevant requirements for roxygen and also am unsure what to include as relevant requiremetns and how to use it to create the rd documentation to go with a package are. I presume the namespace would just have the names fun1 and fun2? and the package description would just be some generic information relating to me...and the function of the package?

any step by step guides would be gladly received.

EDIT: The below is how far I got to start with...

I can get as far as the following to create a pacakge...but cant use roxygen to make the documentation...

package.skeleton(list = c("fun1","fun2"), name = "package1")

and here is where I am not sure if I am missing a bunch of steps or not...

roxygenise("package1")

so when trying to install i get the following error message

system("R CMD INSTALL package1")
* installing to library ‘/Library/Frameworks/R.framework/Versions/2.15/Resources/library’
* installing *source* package ‘package1’ ...
** R
** preparing package for lazy loading
** help
Warning: /path.to.package/package1/man/package1-package.Rd:32: All text must be in a section
*** installing help indices
Error in Rd_info(db[[i]]) : 
  missing/empty \title field in '/path.to.package/package1/man/fun1.Rd'
Rd files must have a non-empty \title.
See chapter 'Writing R documentation' in manual 'Writing R Extensions'.
* removing ‘/Library/Frameworks/R.framework/Versions/2.15/Resources/library/package1’

Answer 1

I'm surprised @hadley says to not use package.skeleton in his comment. I would use package.skeleton, add roxygen comment blocks, then delete all the files in the "man" directory and run roxygenize. However, since Hadley says "Noooooooooo", here's the minimum you need to be able to build a package that passes R CMD check and exports your functions.

Create directory called "package1". Under that directory, create a file called DESCRIPTION and put this in it (edit it appropriately if you like):

DESCRIPTION

Package: package1
Type: Package
Title: What the package does (short line)
Version: 0.0.1
Date: 2012-11-12
Author: Who wrote it
Maintainer: Who to complain to <[e-mail]>
Description: More about what it does (maybe more than one line)
License: GPL

Now create a directory called "R" and add a file for each function (or, you can put both of your functions in the same file if you want). I created 2 files: fun1.R and fun2.R

fun1.R

#' fun1
#' @param x numeric
#' @export
fun1 <- function(x){
    rnorm(100*x)
}

fun2.R

#' fun2
#' @param y numeric
#' @export
fun2 <- function(y){
    rnorm(200*y)
}

Now you can roxygenize your package

R> library(roxygen2)
Loading required package: digest
R> list.files()
[1] "package1"
R> roxygenize("package1")
Updating collate directive in  /home/garrett/tmp/package1/DESCRIPTION 
Updating namespace directives
Writing fun1.Rd
Writing fun2.Rd

Since you mentioned devtools in the title of your Q, you could use the build and install functions from devtools

build('package1')
install('package1')

Or you can exit R and use the tools that come with R to build/check/install.

$ R CMD build package1
$ R CMD check package1_0.0.1.tar.gz
$ R CMD INSTALL package1_0.0.1.tar.gz 

Now, fire up R again to use your new package.

$ R --vanilla -q

library(package1)
fun1(20)
fun2(20)

But, figuring out the minimum requirements is unlikely to help you (or the users of your package) much. You'd be much better off studying one of the many, many packages that use roxgen2.

Here's a better version of the fun1.R file which still doesn't use all the roxygen tags that it could, but is much better than the bare minimum

Modified fun1.R

#' fun1
#'
#' This is the Description section
#'
#' This is the Details section
#'
#' @param x numeric. this is multiplied by 100 to determine the length of the returned vector
#' @return a numeric vector of random deviates of length \code{100 * x}
#' @author your name
#' @seealso \code{\link{fun2}}
#' @examples
#' fun1(2)
#' length(fun1(20))
#' @export
fun1 <- function(x){
    rnorm(100*x)
}

Answer 2

Much later - You could let RoxygenReady prepare your functions with the minimal Roxygen annotation skeleton. It basically brings you from your 2 input functions to GSee's answer, which is the input of Roxygen2.