Skip to content

writing roxygen documentation: Emacs? #6

Closed
yihui opened this Issue Jan 18, 2011 · 6 comments

3 participants

@yihui
GGobi foundation for interactive and dynamic graphics member
yihui commented Jan 18, 2011

I'm not a particularly big fan of Emacs, but Emacs with ESS is really handy for writing roxygen documentation. For example, you do not need to type the prefix ##' for every single line (it will be automatically generated); you can generate a doc template for a function quickly; wrap long lines into shorter ones...

Currently I see there are long lines in the doc, which could be problematic for roxygen (this is a defect in roxygen I've been complaining about). Ideally you should not write too long in a single line, otherwise roxygen will fail.

I do not know if you (Iowans) are interested in trying Emacs. I believe it can save a huge amount of time in writing R docs.

@hadley
GGobi foundation for interactive and dynamic graphics member
hadley commented Jan 18, 2011

I haven't had any problems with roxygen and long lines (although I agree that that should be wrapped) - can you point to a specific problem?

@lawremi
GGobi foundation for interactive and dynamic graphics member
lawremi commented Jan 18, 2011

No idea about this long line issue here, but I'll recommend emacs/ESS. It has increased my productivity immensely. The magit mode is reason enough. There are a lot of text editors out there though.

@yihui
GGobi foundation for interactive and dynamic graphics member
yihui commented Jan 18, 2011

the problem is just long lines in documentation can make roxygen fail; you did not meet this problem probably because you never tried really long lines, e.g.

##' title
##' description
##'
##' @param a long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long line
f <- function(a) {
a
}

roxygen will complain:

Error in do.call(paste, c(trimmed.lines, sep = "\n")) : 
  variable names are limited to 256 bytes
@lawremi
GGobi foundation for interactive and dynamic graphics member
lawremi commented Jan 18, 2011

Obviously a bug in roxygen, but shouldn't that line generally be hard-wrapped, i.e., with a newline? It's longer than 80 chars.

@hadley
GGobi foundation for interactive and dynamic graphics member
hadley commented Jan 18, 2011

Hmmm, I think I might've fixed that bug in my version of roxygen.

@yihui
GGobi foundation for interactive and dynamic graphics member
yihui commented Jan 19, 2011

Usually I do M-q when I write the documentation in Emacs, which can wrap the line automatically, but who knows what the users will do? This bug was not documented anywhere, and in fact I was bitten when I used roxygen for the first time. Later I found it came from a call to paste(), which should have been paste(..., collapse='') rather than do.call(paste, ...).

@yihui yihui closed this May 17, 2011
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.