Implement @Slots tag. Closes #85

NAMESPACE

@@ -18,6 +18,7 @@ S3method(default_usage,"NULL")
 S3method(default_usage,"function")
 S3method(default_usage,data)
 S3method(default_usage,s3method)
+S3method(default_usage,s4class)
 S3method(default_usage,s4method)
 S3method(format,alias_tag)
 S3method(format,arguments_tag)
@@ -40,6 +41,7 @@ S3method(format,rd_tag)
 S3method(format,references_tag)
 S3method(format,section_tag)
 S3method(format,seealso_tag)
+S3method(format,slot_tag)
 S3method(format,source_tag)
 S3method(format,title_tag)
 S3method(format,usage_tag)

NEWS

@@ -1,6 +1,8 @@
 roxygen2 3.0.0
 --------------
 
+* `@slot` tag allows you to document the slots of a S4 class.
+
 * Infix functions now escaped correctly in NAMESPACE. (Thanks to Peter 
   Meilstrup, #111)
 

R/rd-file-api.R

@@ -24,8 +24,8 @@ names.rd_file <- function(x) {
 format.rd_file <- function(x, ...) {
   tags <- as.list(x[[1]])
   order <- c("docType", "encoding", "name", "alias", "title", "format",
-    "source", "usage", "arguments", "value", "description", "details", "note",
-    "section", "examples", "author", "references", "seealso", "concept",
+    "source", "usage", "arguments", "value", "description", "details", "slot", 
+    "note", "section", "examples", "author", "references", "seealso", "concept",
     "keyword")
 
   tags <- tags[intersect(order, names(tags))]

R/rd-tag-api.R

@@ -138,6 +138,16 @@ format.section_tag <- function(x, ...) {
     collapse = "\n")
 }
 
+#' @S3method format slot_tag
+format.slot_tag <- function(x, ...) {
+  names <- names(x$values)
+  items <- str_c("\\item{\\code{", names, "}}{", x$values, "}", collapse = "\n\n")
+  str_c("\\section{Slots}\n\n",
+    "\\itemize{\n", 
+    items,
+    "\n}\n")
+}
+
 #' @export
 format.examples_tag <- function(x, ...) {
   values <- str_c(x$values, collapse = "\n")

R/roclet-rd.R

@@ -28,6 +28,7 @@ register.preref.parsers(parse.value,
 
 register.preref.parsers(parse.name.description,
                         'param',
+                        'slot',
                         'method')
 
 register.preref.parsers(parse.name,
@@ -173,6 +174,9 @@ register.preref.parsers(parse.default,
 #'
 #'  \item{\code{@@source text}}{The original source of the data.}
 #'
+#'  \item{\code{@@slot name description}}{Describe the slots of an S4 class
+#'    in a standard way. Slots will be listed in their own section.}
+#'
 #'}
 #' @family roclets
 #' @examples
@@ -320,6 +324,7 @@ roclet_rd_one <- function(partitum, base_path) {
   }))
   add_tag(rd, usage_tag(partitum))
   add_tag(rd, process.arguments(partitum))
+  add_tag(rd, process.slot(partitum))
   add_tag(rd, process.docType(partitum))
   add_tag(rd, process_had_tag(partitum, 'note'))
   add_tag(rd, process_had_tag(partitum, 'family'))
@@ -413,6 +418,16 @@ process.arguments <- function(partitum) {
   new_tag("arguments", desc)
 }
 
+process.slot <- function(partitum) {
+  params <- partitum[names(partitum) == "slot"]
+  if (length(params) == 0) return() 
+
+  desc <- str_trim(sapply(params, "[[", "description"))
+  names(desc) <- sapply(params, "[[", "name")
+
+  new_tag("slot", desc)
+}
+
 # If \code{@@examples} is provided, use that; otherwise, concatenate
 # the files pointed to by each \code{@@example}.
 process.examples <- function(partitum, base_path) {

R/usage.R

@@ -46,6 +46,9 @@ default_usage.s4method <- function(x) {
   function_usage(x$name, formals(x$value), s4method)
 }
 
+#' @export
+default_usage.s4class <- function(x) NULL
+
 # Usage:
 # replacement, infix, regular
 # function, s3 method, s4 method, data

inst/tests/test-rd.R

@@ -295,3 +295,15 @@ test_that("deleted objects not documented", {
   expect_equal(names(out), "f2.Rd")
 })
 
+
+
+test_that("@slot creates a new section and lists slots", {
+  out <- roc_proc_text(roc, "
+      #' Important class.
+      #' 
+      #' @slot a slot a
+      #' @slot b slot b
+      setClass('test')
+    ")[[1]]
+  expect_equal(get_tag(out, "slot")$values, c(a = "slot a", b = "slot b"))
+})

man/rd_roclet.Rd

@@ -180,6 +180,10 @@ rd_roclet()
   \item{\code{@source text}}{The original source of the
   data.}
 
+  \item{\code{@slot name description}}{Describe the slots
+  of an S4 class in a standard way. Slots will be listed in
+  their own section.}
+
   }
 }
 \examples{