If a commented line inside R code contains 2 straight single quotes, document() throws erroneous warning

[bestdan]

#' @title Test Bug
#' @author Daniel Egan
#' @param x  
#' @return Nothing
#' @export
#' @examples
#' testFun(x)


testFun <- function(x){

  #' Warning1'
  return(TRUE)
}

Produces

> Warning messages:
> 1: @examples [TestFun.R#8]: mismatched braces or quotes 

[bestdan]

I should note, the toughest part about this was that the warning is ascribed to the roxygen block ABOVE the actual R code which is causing it. There are no mis-matched braces or quotes in the examples block, which is SUPER confusing.

If the warning correctly identified the line where the error was (in the R code, not the roxygen block), this would have been much easier to figure out.

[hadley]

As I mentioned in #426, this is because roxygen now processes roxygen comments inside functions. I think it's hard to get a better error message here, because from roxygen's perspective, that line is part of the examples which start at line 8.

cc @krlmlr

[krlmlr]

(I'm responsible for this.) It shouldn't be too hard to add a compatibility switch, if this causes too much trouble. However, changing the comment from #' to a plain # should resolve this issue, and I think that plain comments are not checked.

[bestdan]

Ok, but note that if the sentence includes ANY subsequent ', such as in a contraction, it will blow up.

#' This ain't gonna work

[hadley]

Yes, because that's not valid R code

[bestdan]

Isn't it technically not valid roxygen2 code?

R appears to have no problem with it.

[hadley]

You're generating

#' @examples
#' testFun(x)
#' Warning1'

Which makes:

testFun(x)
warning1'

which is not valid

[bestdan]

Completely agree. But the fact that Warning1 shows up is due to roxygen2 parsing of the files and including it.

I see what you're saying, and perhaps it's the right thing in the long run. I personally don't see a use case where I write roxygen documentation inside the function (could you share an example use case?).

It ate up most of my day yesterday, fixing files with #' in the function body. Since a big point of this is to make it easier for people to document files, more helpful error messages that correctly identify and communicate the error would help people who get hit with this a lot.

[hadley]

As I said in the other thread, it's a step along the road to support for R6 and RC.

We didn't expect people to use roxygen comments instead of normal comments inside functions and unfortunately it's hard to get a more informative error message because of the way parsing works.

[krlmlr]

Here's a simple sed script that should convert most inline roxygen2 comments (those with indentation using space) to plain comments:

sed -r -i"" "s/( +#)'/\1/" R/*

Run it from your package's directory. I've tested it on Ubuntu, I hope I got the -i switch right so that it also works on OS X.

[bestdan]

@krlmlr Thank you, that's very helpful. I appreciate the effort.

I've actually fixed everything already, but I'm sure others will benefit from that. Perhaps a stack-overflow question that you ask and answer?

[krlmlr]

You ask, I answer ;-)

[bestdan]

Done:

http://stackoverflow.com/questions/33529903/roxygen2-version-5-0-incorrectly-creates-documentation-when-occurs-inside-f