Does RStudio support any automated roxygen template creation?
In Emacs-ESS, C-x C-o will produce an roxygen template for a function. For example, it will automagically convert this:
foo <- function(x,y) x+y
into this:
##' .. content for \description{} (no empty lines) ..
##'
##' .. content for \details{} ..
##' #title
##' #param x
##' #param y
##' #return
##' #author David
foo <- function(x,y) x+y
Does similar functionality exist within RStudio?
updates
as of ESS 12.09-2, the command has been changed to C-c C-o C-o
this feature has been implemented in Rstudio: CTRL+ALT+SHIFT+R
(Converting #Crops comment into a full answer)
In RStudio v0.99 there is a new option under the "Code" menu for .R files: "Insert Roxygen Skeleton". There is an image of it in RStudio's blog post about v0.99 preview.
The silence that followed your question should tell you something...
The answer, currently, is NO is doesn't. I know of several people who use EMACS for precisely this reason, and would not consider switching to RStudio until that has full roxygen support.
That said, there has been some discussion about this between users and the makers of RStudio. Considering all the cool things that have been added to RStudio recently, I would not be surprised to see it happen. In fact, I think it is quite likely it will happen. But don't hold your breath for it, it may be a long wait...
Alternatively you can use the R package RoxygenReady to create Roxygen skeletons / Roxygen templates.
My solution was to use a text expander (PhraseExpress in my case) to do this.
Related
Now and then I embrace project specific code in R packages. I use the documentation files as suggested by Writing R Extensions to document the application of the code.
So once you set up your project and did all the editing to the .Rd files,
how do you manage a painless and clean versioning without rewriting or intense copy-pasting of all the documentation files in case of code or, even worse, code structure changes?
To be more verbose, my current workflow is that I issue package.skeleton(), do the editing on the .Rd-files followed by R CMD check and R CMD build. When I do changes to my code I need to redo the above maybe appending '.2.0.1' or whatever in order to preserve the precursor version. Before running the R CMD check command I need to repopulate all the .Rd-files with great care in order to get a clean check and succsessful compilation of Tex-files. This is really silly and sometimes a real pain, e.g. if you want to address all the warnings or latex has a bad day.
What tricks do you use? Please share your workflow.
The solution you're looking for is roxygen2.
RStudio provides a handy guide, but briefly you document your function in-line with the function definition:
#' Function doing something
#' Extended description goes here
#' #param x Input foo blah
#' #return A numeric vector length one containing foo
myFunc <- function(x) NULL
If you're using RStudio (and maybe ESS also?) the Build Package command automagically creates the .Rd files for you. If not, you can read the roxygen2 documentation for the commands to generate the docs.
Say I want to comment out a #' #export tag - what is the documented way to do so?
Adding a # in front (as with standard R comments) doesn't seem to work: ##' #export foo still leads to export(foo) in my NAMESPACE file.
Can I also block-comment out entire roxygen sections in RStudio?
Roxygen comments involve prefixing lines with #'.
When writing and testing examples for functions, it's nice to be able to toggle the comments on and off. I could copy and paste the code back and forward to vim and remove or add those comments, but that's not very elegant.
Is there any easy way to toggle roxygen comments in Rstudio?
Alternatively, is there another way to efficiently run example R code that is commented out by roxygen comment characters?
Update: Thinking laterally, I suppose using #example examples/foo.r is an alternative way of avoiding having to use Roxygen comments for the actual example code (i.e., by sourcing the example from a file, i.e., examples/foo.r).
With respect to your proposed alternative:
Alternatively, is there another way to efficiently run example R code that is commented out by roxygen comment characters?
If you press CTRL+[Enter] within a Roxygen2 #examples block, Rstudio will send the selected code (line or highlighted section) to the R console. To use just declare the #examples code block on a line preceding your roxygen commented code.
#' #examples
#' ... your original roxygen commented code ...
You can put an #examples block anywhere in your code. This becomes a drag if you are developing a package and you are using the block for its intended purpose.
If you are looking for a way to toggle code, I would use the approach proposed by #Roman in in the comments to your question.
You can write your own function that extract example code from your R file. This is analogous to purl in knit package or Stangle. Here an example of what you can do. The function is not efficient but I write it just to show the idea. It should be a good start point. It assumes also that you already source your R file or at least that the documented function already exist in the R session.
purl.examples <- function(fileName){
ll <- readLines(fileName)
ex.lines <- grep('#examples',ll) ## get the example's lines
## for each example loop till
## there is no comment (inefficient)
examples <- lapply(ex.lines , function(x){
i <- x+1
code <- list()
while(grepl("#'",ll[i])){
l <- c(code,gsub("#'","",ll[i],fixed=TRUE))
i <- i+1
}
code
})
}
Then you can call it like this for example:
lapply(purl.examples('code.R'),
function(ex) eval(parse(text=ex))) ## safer to use evaluate package here
Actual question
How do I avoid Rd file name conflicts when
a S4 generic and its method(s) are not necessarily all defined in the same package (package containing (some of) the custom method(s) depends on the package containing the generic) and
using roxygenize() from package roxygen2 to generate the actual Rd files?
I'm not sure if this is a roxygen2 problem or a common problem when the generic and its method(s) are scattered across packages (which IMHO in general definitely is a realistic use-case scenario if you follow a modular programming style).
What's the recommended way to handle these situations?
Illustration
In package pkga
Suppose in package pkga you defined a generic method foo and that you've provided the respective roxygen code that roxygenize() picks up to generate the Rd file:
#' Test function
#'
#' Test function.
#'
#' #param ... Further arguments.
#' #author Janko Thyson \email{janko.thyson##rappster.de}
#' #example inst/examples/foo.R
#' #docType methods
#' #rdname foo-methods
#' #export
setGeneric(
name="foo",
signature=c("x"),
def=function(
x,
...
) {
standardGeneric("xFoo")
}
)
When roxygenizing() your package, a file called foo-methods.Rd is created in the man subdirectory that serves as the reference Rd file for all methods that might be created for this generic method. So far so good. If all of the methods for this generic are also part of your package, everything's good. For example, this roxygen code would make sure that documentation is added to foo-methods.Rd for the ANY-method of foo:
#' #param x \code{ANY}.
#' #return \code{TRUE}.
#' #rdname foo-methods
#' #aliases foo,ANY-method
#' #export
setMethod(
f="foo",
signature=signature(x="ANY"),
definition=cmpfun(function(
x,
...
) {
return(TRUE)
}, options=list(suppressAll=TRUE))
)
However, if package pkga provides the generic for foo and you decide in some other package (say pkgb) to add a foo-method for x being of class character, then R CMD check will tell you that there is a name clash with respect to Rd file names and/or aliases (as there already exists a Rd file foo-methods.Rd in pkga):
In package pkgb
#' #param x \code{character}.
#' #return \code{character}.
#' #rdname foo-methods
#' #aliases foo,character-method
#' #export
setMethod(
f="foo",
signature=signature(x="character"),
definition=cmpfun(function(
x,
...
) {
return(x)
}, options=list(suppressAll=TRUE))
)
To be more precise, this is the error that's thrown/written to file 00install.out
Error : Q:/pkgb/man/foo-methods.Rd: Sections \title, and \name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package 'pkgb'
Due dilligence
I tried to change the values for #rdname and #aliases to foo_pkgb* (instead of foo*), but \title and \name still are set to foo when roxygenizing and thus the error remains. Any ideas besides manually editing the Rd files generated by roxygenize()?
EDIT 2012-12-01
In light of starting the bounty, the actual question might get a slightly broader flavor:
How can we implement some sort of an "inter-package" check with respect to Rd files and/or how can we consolidate S4 method help files scattered across packages into one single Rd file in order to present a single source of reference to the end-user?
The basic question is indeed "roxygenize"-only.
That's why I never had seen the problem.
While there are good reasons for the roxygenizing approach of package development,
I still see a very good reason not to go there:
Plea for much less extreme roxygenation
The resulting help pages tend to look extremely boring, not only the auto generated *.Rd files but also the rendered result.
E.g.
examples are often minimal, do not contain comments, are often not well formatted (using space, / new lines /..)
Mathematical issues are rarely explained via \eqn{} or \deqn{}
\describe{ .. } and similar higher level formatting is rarely used
Why is that? Because
1) reading and editing roxygen comments is so much more
"cumbersome" or at least visually unrewarding
than reading and editing *.Rd files in ESS or Rstudio or (other IDE that has *.Rd support built in)
2) If you are used that documentation
is the thing that's automatically generated at the end of your package building/checking
you typically tend to not considerung well written R documentation as something important
(but rather your R code, to which all the docs is just a comment :-)
The result of all that: People prefer writing documentation about their functions in vignettes or even blogs, github gists, youtube videos, or ... where it is very nice at the time of authoring, but is
pretty much detached from the code and bound to get outdated and withering (and hence, via Google search misleading your useRs)
--> The original motivation of roxygen of having code and documentation in the same place is entirely defeated.
I like roxygen and use it extensively at the time I create a new function...
and I keep and maintain it as long as my function is not in a package, or is not exported.
Once I decide to export it,
I run (the ESS equivalent of) roxygenize() once
and from then on take the small extra burden of maintaining a *.Rd file that is well formatted, contains its own comments (for me as author), has many nice examples, has its own revision control (git / svn / ...) history, etc.
I managed to generate NAMESPACE and *.Rd files for S4 methods for generics defined in another package than mine.
It took me the following steps:
Create NAMESPACE by hand as a workaround to a known roxygen2 bug.
Writing a NAMESPACE by hand is not so difficult at all!
Switch off NAMESPACE generation by roxygen2 in RStudio:
Build > more > Configure build tools > configure roxygen > do not use roxygen2 to generate NAMESPACE.
import the package containing the generic and export the S4 methods using exportMethods.
Write separate roxygen2 documentation for each of the S4 methods. Do not combine roxygen2 documentation (as I generally do for different methods of the same generic).
Add explicit roxygen tags #title and #description to the roxygen documentation of the S4 methods. Write #description explicitly, even if its value is identical as #title.
That makes it work for me.
Does RStudio support any automated roxygen template creation?
In Emacs-ESS, C-x C-o will produce an roxygen template for a function. For example, it will automagically convert this:
foo <- function(x,y) x+y
into this:
##' .. content for \description{} (no empty lines) ..
##'
##' .. content for \details{} ..
##' #title
##' #param x
##' #param y
##' #return
##' #author David
foo <- function(x,y) x+y
Does similar functionality exist within RStudio?
updates
as of ESS 12.09-2, the command has been changed to C-c C-o C-o
this feature has been implemented in Rstudio: CTRL+ALT+SHIFT+R
(Converting #Crops comment into a full answer)
In RStudio v0.99 there is a new option under the "Code" menu for .R files: "Insert Roxygen Skeleton". There is an image of it in RStudio's blog post about v0.99 preview.
The silence that followed your question should tell you something...
The answer, currently, is NO is doesn't. I know of several people who use EMACS for precisely this reason, and would not consider switching to RStudio until that has full roxygen support.
That said, there has been some discussion about this between users and the makers of RStudio. Considering all the cool things that have been added to RStudio recently, I would not be surprised to see it happen. In fact, I think it is quite likely it will happen. But don't hold your breath for it, it may be a long wait...
Alternatively you can use the R package RoxygenReady to create Roxygen skeletons / Roxygen templates.
My solution was to use a text expander (PhraseExpress in my case) to do this.