How is S4 class definition done in a package and how is it documented properly?

Question

Once I defined a class I wonder where to out in a package. Should just create a file classDefintions.R containing my S4 class definition and put it to the R folder? If so, how can I document it properly? Is there a .rd file template for S4 classes around?

I found this post on Roxygen2 but I might be a few step behind here. How is it basically done and located?

Answer 1

Just like other R objects, S4 class and method definitions are documented with *.Rd files stored in the man subdirectory of the package source.

Besides reading the relevant section of R-exts, I'd suggest downloading and looking at the source of a well-written S4-based package with which you're familiar. (For me that would likely be sp, lme4 or Matrix.)

Finally, the methods package includes two nifty utility functions, promptClass() and promptMethods() that will fill out a skeleton *.Rd file for any S4 class or method defined in the current R session.

As an example that uses R objects defined in the sp package, you could do this:

library(sp)     ## for some example S4 classes and methods

promptClass("SpatialPolygons")
# A shell of class documentation has been written to the file
# ‘SpatialPolygons-class.Rd’.

promptMethods("bbox")
# A shell of methods documentation has been written to the file
# ‘bbox-methods.Rd’.

And then take a look at the files SpatialPolygons-class.Rd and bbox-methods.Rd to see how much work those functions will save you!

---

Edit: After a quick reread of your question, I see you were also asking about how to include the methods and classes themselves. My advice for that's basically the same: read the manual and "use the source" (making sure to also look at how exportClasses() and exportMethods() directives in the NAMESPACE file are used to export S4 objects.)