@slot causes warning: "slot is an unknown key"

[joey711]

In various roxygen tutorials I've come across the @slot tag as the suggested tag for documenting each slot of a particular S4 class. However, it seems this is not actually being supported, in this fork or the current CRAN release of roxygen or roxygen2.

I just found a brief mailing-list post declaring that in fact @slot is not supported, and developers should use an itemized list instead. This seems sub-optimal, so I thought I would see if anyone here has a different opinion.

So which is it?

A -- Itemized list?

B -- @slot works, but with some special version of roxygen that I'm unfamiliar with.

C -- Some alternative tag for specifying slots, like @param, that would accomplish the same thing.

Thanks in advance for any help.

[joey711]

Just a note, here is the link to the development mailing list where I obtained option A:

http://lists.r-forge.r-project.org/pipermail/roxygen-devel/2008-November/000009.html

[hadley]

Could you please describe what the slot tag should do? A small example would also be useful.

[joey711]

I thought this would probably work similar to, or exactly like, the @param tag. It remains up to the user to properly describe for each slot the expected class, what it is for, and any defaults. @param might even be the appropriate tag instead of @slot. Or perhaps both can exact the same result?

What result? Well, a good doc example -- though not well typeset -- is ?"ltrMatrix-class" from the Matrix package. Ideally the "Slots" section is typeset exactly like the Arguments section for functions / methods. "Extends" is an important section Matrix includes in its class-doc, and I've included it (optimistically) in my example below.

I poked around (briefly) looking at documentation from S4 classes of the Matrix and Biostrings packages. There seem to be some disagreement about whether the class documentation should explicitly describe the class, what it inherits, and what its slots are (Matrix:: ?"ltrMatrix-class"); or alternatively, a number of examples of that particular class in action with application-specific subheadings (see Biostrings:: ?"XStringSet-class"). I think both are useful, but I'm in favor of the former for consistency, and because those extra details from the latter can easily go in a Description or Examples sections.

#' The header for mynewclass documentation.
#'
#' Some details about this class and my plans for it in the body.
#'
#' @param myslot1 A logical. Toggles something.
#' @param myslot2 An integer. Specifies the number of something.
#' @param myslot3 A data.frame. Holds key data
#'
#' @extends Class \code{"character"} directly. 
#'
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @exportClass mynewclass
setClass("mynewclass",
    representation(myslot1="logical",
        myslot2="integer",
        myslot3="data.frame"),
    contains = "character"
)

This is getting ahead and definitely a separate issue/feature, but, the Matrix package also has a nice convention in which it has a "Methods" section near the bottom that lists the method-name and signature for many (all?) of the methods that list that particular class in their signature ( see ?"ldenseMatrix-class"). A great cross-ref feature for exploring a package.

[tobias-verbeke]

The current implementation does not pass the Rd checks, primarily because
\section{Slots} should become \section{Slots}{...}. Some other improvements
are possible as well.

Current (erroneous) form

\section{Slots}
\itemize{
  \item{a}{Object of class \code{"numeric"}}
  \item{b}{Object of class \code{"character"}}
}

could become

\section{Slots}{
  \describe{
    \item{\code{a}:}{Object of class \code{"numeric"}.}
    \item{\code{b}:}{Object of class \code{"character"}.}
  }
}

Can this ticket be reopened? Should I prepare a pull request?

[hadley]

A new ticket would be preferred please.

[tobias-verbeke]

thanks - created ticket #84 and sent a pull request