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:

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

Flagon

I have never seen this behaviour with roxygen2, but I also don't use roxygenise. Instead, I use document() in the package devtools - this makes use of roxygenise but this step is hidden. Anyway, my setup seems the same as yours: Windows 7 + CygWin + roxygen2 v2.2.2. You have my sympathy, but sadly I can' offer advice. – Selwyn

I had a quick glance over the roxygen2 source code and I can't see any obvious causes (like system calls) - maybe encoding ??!! I'll try devtools and see if I get the same problem. I did spend ages thinking I'd made a mistake in my markup before I realised that it was only in Cygwin that I had that problem. – Flagon

Aha! I had a chat with Bill Venables (!) who put me on to the fact that you can actually run your Windows R in cygwin (ie the one in Program Files/R/R-2.14.2/bin). I've been using the R you get from cygwin's package manager. Lo and behold, using the Windows R works. So perhaps it is a bug within the R from cygwin's package manager as opposed to roxygen2. – Flagon

Can you please write your results as an answer (as opposed to editing the question). In that way we can mark the question as answered. – Selwyn

Sure. I don't really consider the question answered though, the bug is still there - this is just a workaround. – Flagon

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.

Flagon