3

Possible Duplicate:
How to properly document S4 class slots using Roxygen2

I would like to build a package that contains S4 classes using R Studio and roxygen2. I had already documented all my functions using roxygen2 syntax when I introduced a couple of S4 classes to my package.

Now I realized that there's no '@slot' functionality out-of-the-box. So I wonder how can I keep all my documentation work for the other functions and document the S4 classes manually like suggested in this thread?

Or in other words which workflow would you recommend to built a package that contains both old school functions and S4 classes?

EDIT: Would you recommend to configure R Studio built tools not to create .Rd files. roxygenize manually and then add the info afterwards? Still this would lead to overwriting the manually generated .Rd files of the classes...

Community
  • 1
  • 1
Matt Bannert
  • 27,631
  • 38
  • 141
  • 207
  • @Hans0I0 What exactly is your problem here? Do what is said in that thread you link to, and eg http://www.inside-r.org/questions/how-properly-document-s4-class-slots-using-roxygen2. Make sure you export them correctly.µ – Joris Meys Nov 30 '12 at 09:27
  • 1
    My problem is the R Studio standard workflow. Everytime I hit build `Roxygen` is used to create .Rd files. If I add the .Rd files of the classes manually like suggested in this thread, next time I run build from R Studio these manual changes are overwritten. – Matt Bannert Nov 30 '12 at 09:41
  • 1
    But you don't have to add the .Rd files manually. You just have to use the describe to create your slots. – Joris Meys Nov 30 '12 at 10:25

1 Answers1

4

General info on roxygen and S4 classes

The first version of roxygen had an @slot tag, but that version isn't maintained any more in favor of roxygen2. So it's advised against to use that old version.

As for now, roxygen2 doesn't have real support for S4 classes. Hadley is working hard to make that happen in roxygen3 (https://github.com/hadley/roxygen3). In case you want to give it a shot and feel brave: install roxygen3 from github and try the development version. Note that this version eventually will be incoorporated into roxygen2, so in time the problem will solve itself.

Regarding your workflow:

I personally always find it a bad idea to combine using roxygen and manually written .Rd files. But if you must, you can send the output of roxygen to a different directory using the argument roxygen.dir. This way you can copy whatever you want back into the package directory without overwriting the manually written files.

roxygenise("./mypackage", roxygen.dir="./myroxygendir")

What I would do, is simply use roxygen2 to write the Rd files for your classes as explained in the thread you link to. You don't have to add them manually like you believe for some unknown reason. You just use the #' to indicate the Rd block like always, and use whatever is given in the thread you link to. If you want to make the slots a separate section, you can do that using the @section tag like in the example below.

An example of how to add Slots for the moment using roxygen2 :

#' The MY class
#'
#' This class blabla yadayada
#'
#'@section Slots:
#'  \describe{
#'    \item{\code{aslot}:}{Object of class \code{"numeric"}, containing 
#'whatever and a bit more}
#'    \item{\code{anotherslot}:}{Object of class \code{"character"}, containing
#' strings.}
#'  }
#'
#' @note Yes, you can add notes
#' @name MY 
#' @rdname MY
#' @aliases MY-class
#' @exportClass MY
#' @author Joris Meys
setClass("MY",
         representation=representation(aslot="numeric",
                                       anotherslot="character"
                                       )
Community
  • 1
  • 1
Joris Meys
  • 106,551
  • 31
  • 221
  • 263
  • Definitely will check out roxygen3's dev version. Needless to say I am a big fan of Hadley's work. However, currently I just want to avoid a lack of focus finishing my package. Though I like both of your answers I can only +1 :) . I didn't realize before your comment that I can actually have \describe and @params in the same document. It throws a warning in R Studio but works. Thanks Joris! – Matt Bannert Nov 30 '12 at 10:58
  • @hans0l0 If you have an S4 class, I wonder why you need `@param` in the same document. Personally, I keep my class files separated from getters, setters and what-not. That's easier to keep an overview for me, and it doesn't give warnings in RStudio. Be sure to check http://stackoverflow.com/questions/13510234/how-to-specify-in-which-order-to-load-s4-methods-when-using-roxygen2 for use of the `@include` tag – Joris Meys Nov 30 '12 at 11:05
  • You are right. I don't use no `@param`. just meant to say I did not know I could combine the @ syntax with `\describe`. Ah and thx for the link – indeed very educating... – Matt Bannert Nov 30 '12 at 11:26