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:

1. 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')
   

2. 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 )
   }
   

3. Run R and generate documentation:

   library(roxygen2)
   roxygenise('test')
   

4. 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!).

Answer 1

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.