back to first page ..
back to Recipes for EDA CookBook R

Using rOxygen to comment the source

• you need to build a package, it works like javadoc, which is very good.
• A good idea, but roxygen is not sufficiently developped yet so I'm quite disappointed, but progress should be made soon (from what can be read in the net)
• It does not work so far on S4 packages (from my experience ther is a bug, from others also, sparse comments on the web)
• It needs a more "verbose" return to be able to understand where the error come from => see below for modified function
• It is a loss of time with description file (as described in the vignette), so just write your description after building the package.

Below an example with package calcmig and modified function.

library(roxygen) 
# ici je refais la fonction roxygen pour savoir ou elle plante
# j'utilise la fonction utils::getAnywhere()$objs[[1]] pour récupérer les éléments du namespace
# et ::: pour utiliser les fonctions non exportées
setwd("C:/Documents and Settings/cedric/Mes documents/Migrateur/programmes/workspace3.5/calcmigv0.3/")
roxygenize.ced=function (package.dir, roxygen.dir = NULL, copy.package = TRUE, 
		overwrite = TRUE, unlink.target = FALSE, use.Rd2 = FALSE) 
{
	if (is.null(roxygen.dir)) 
		roxygen.dir <- sprintf(utils::getAnywhere("ROXYGEN.DIR")$objs[[1]], package.dir)
	man.dir <- file.path(roxygen.dir, utils::getAnywhere(MAN.DIR)$objs[[1]])
	inst.dir <- file.path(roxygen.dir, utils::getAnywhere(INST.DIR)$objs[[1]])
	doc.dir <- file.path(inst.dir, utils::getAnywhere(DOC.DIR)$objs[[1]])
	namespace.file <- file.path(roxygen.dir, utils::getAnywhere(NAMESPACE.FILE)$objs[[1]])
	package.description <- file.path(package.dir, utils::getAnywhere(DESCRIPTION.FILE)$objs[[1]])
	roxygen.description <- file.path(roxygen.dir, utils::getAnywhere(DESCRIPTION.FILE)$objs[[1]])
	skeleton <- c(roxygen.dir, man.dir, doc.dir)
	if (copy.package) 
		roxygen:::copy.dir(package.dir, 
				roxygen.dir, 
				unlink.target = unlink.target, 
				overwrite = overwrite,
				verbose = FALSE)
	for (dir in skeleton) dir.create(dir, recursive = TRUE, showWarnings = FALSE)
	r.dir <- file.path(package.dir, utils::getAnywhere(R.DIR)$objs[[1]])
	files <- as.list(list.files(r.dir, pattern = "\\.(R|r)$",
					recursive = TRUE,
					full.names = TRUE,
					all.files = TRUE))
	Rd <- {
		if (use.Rd2) 
			make.Rd2.roclet(man.dir)
		else make.Rd.roclet(man.dir)
	}
	print("making Rd files")
	for (i in 1:length(files)){
		print(files[[i]])
		do.call(Rd$parse, as.list(files[[i]]))
	}
	print("building namespace")	
	namespace <- make.namespace.roclet(namespace.file)
	for (i in 1:length(files)){
	do.call(namespace$parse, as.list(files[[i]]))
    }
	collate <- make.collate.roclet(merge.file = package.description, 
			target.file = roxygen.description)
	collate$parse.dir(r.dir)
}

roxygenize.ced(package.dir="prog/calcmigv03",roxygen.dir='prog/calcmigv03',
		copy.package=FALSE,overwrite=TRUE,unlink.target=FALSE,use.Rd2=FALSE)
# this one works, but package are not really well documented
roxygenize(package.dir="prog/calcmigv03",roxygen.dir='prog/calcmigv03',
copy.package=TRUE,overwrite=TRUE,unlink.target=FALSE,use.Rd2=TRUE)