roxygen2 + cygwin + default parameter = truncated `\usage` section
Question
I have a package for R I've been developing under Linux, and the horrible time has come where I'm testing it under Windows.
The documentation is done using roxygen, and I am using cygwin to build the package.
The thing is, when I roxygenise('test-package')
, roxygen truncates the \usage
section of the documentation to one character. It does this to some but not all of my functions, and I can't figure out the pattern.
This does not occur when run the same command (i.e. roxygenise('test-package')
from the R prompt) under Linux or Windows - just Cygwin under Windows (using R devtools + command prompt from windows isn't an option for me - it's part of a big project with Makefiles etc).
In all cases, I am using roxygen v2.2.2.
Update:
This appears to occur for any function with a default parameter.
I've boiled it down to one reproducible example, trimmed down as much as possible to isolate the problem:
From R:
# this function used to trim strings, but I've stripped it right down # to eliminate it as a cause of the problem trim <- function(x='asdf') { return( x ) } package.skeleton('test')
modify
trim.R
(in test/R) and add the following roxygen to the top, so the file looks like:#' trim white spaces from a string #' #' @param x string or vector of strings to trim #' @return x trimmed. #' @export trim <- function(x='asdf') { return( x ) }
Run R and generate documentation:
library(roxygen2) roxygenise('test')
Look at the resulting
trim.Rd
file (in test/man):\name{trim} \alias{trim} \title{trim white spaces from a string} \usage{ t } \arguments{ ... # rest of .Rd file - nothing wrong here.
See how there's just a \usage{t}
??
Of course, when one runs R CMD check
one gets an error about documented arguments not appearing in the \usage
, but that's because \usage
got truncated.
Does anyone know why this occurs and how I can work around it? Perhaps something in roxygen2
that relies on something that works in Mac, Windows & Linux but not Cygwin?
cheers (I've been tearing my hair out over this).
Update #2:
I have been using R installed from Cygwin's package manager, as opposed to my Windows R (ie the one in C:/Program Files/R/R-2.14.2/bin
) - I didn't realise that Windows R would work under Cygwin.
If I use Windows R in Cygwin, the bug goes away. If I use Cygwin R in Cygwin, the bug is present.
I can only assume this is some bug related to Cygwin R, as opposed to roxygen2.
For now I will use the workaround of using Windows R within cygwin (in fact, now that I know I can do this, there's no need for the Cygwin R anyway!).
Solution
This is not a fix, but a workaround.
I have been using R installed from Cygwin's package manager, as opposed to my Windows R (ie the one in C:/Program Files/R/R-2.14.2/bin) - I didn't realise that Windows R would work under Cygwin.
If I use Windows R in Cygwin, the bug goes away. If I use Cygwin R in Cygwin, the bug is present.
I can only assume this is some bug related to Cygwin R, as opposed to roxygen2.
For now I will use the workaround of using Windows R within cygwin (in fact, now that I know I can do this, there's no need for the Cygwin R anyway). This still gives me access to linux commands like make
, sed
and grep
, but allows me to get the documentation working.
The problem still remains that the Cygwin-R in Cygwin (not Windows-R in Cygwin) causes this bug, but perhaps it is not related to roxygen2 any more.