Documenting with roxygen2

• S3 classes/methods
• S4 classes
• S4 methods

S3 classes

Source: http://stackoverflow.com/questions/7198758/roxygen2-how-to-properly-document-s3-methods

An example based on roxygen2:

#' S3 class MyClass.
#' @exportClass MyClass
#

#' @export MyMethod
MyMethod <- function(x, ...) UseMethod("MyMethod)

#' @export 
MyMethod.MyClass <- function(object, data , sName="s" , yName="y" , ...)

S4 classes

Objective: avoid 'R CMD check' error "Undocumented S4 classes".

Rules

• One can have three parts of code: class declaration, class constructor and a wrapper function.
• Documenting part 1
  • @name tag: "Sensor-class".
  • @rdname tag: "Sensor-class".
  • @exportClass tag: "Sensor".
• Documenting parts 2 and 3
  • Use @rdname the same as in part 1 ("Sensor-class").
  • The @alias tags will be added respectively.

Part 1: declaration of the class.

#' Class Sensor.
#'
#' Class \code{Sensor} defines a gas sensor device.
#'
#' @name Sensor-class
#' @rdname Sensor-class
#' @exportClass Sensor
setClass(Class = "Sensor", 
  representation = representation(
    type = "character", num = "numeric"),  
  validity = validSensor
)

Part 2: constructor of the class.

#' Constructor method of Sensor Class.
#'
#' @name Sensor
#' @rdname Sensor-class
setMethod("initialize", "Sensor", function(.Object,
  type = "character", num = "numeric", ...)  
{ 
  if(missing(type)) type <- "polymeric"
  if(missing(num)) num <- 1  
      
  validObject(.Object)      
  return(.Object)
})

Part 3: wrapper function (optional).

#' Wrapper function Sensor.
#'
#' @name Sensor
#' @rdname Sensor-class
#' @export
Sensor <- function(...) new("Sensor", ...) 

Resulted file "Sensor-class.Rd".

\name{Sensor-class}
\alias{Sensor}
\alias{Sensor-class}
\title{Class Sensor.}
\usage{
  Sensor(...)
}
\description{
  Class \code{Sensor} defines a gas sensor device.

  Constructor method of Sensor Class.

  Wrapper function Sensor.
}

S4 methods

Objective: avoid 'R CMD check' error "Undocumented S4 methods".

Methods in separated Rd files

Part 1: setGeneric

#' Method num.
#' @name num
#' @rdname num-methods
#' @exportMethod num
setGeneric("num", function(x) standardGeneric("num"))

#' Method type.
#' @name type
#' @rdname type-methods
#' @exportMethod type
setGeneric("type", function(x) standardGeneric("type"))

Part 2: setMethod

#' @rdname num-methods
#' @aliases num,ANY-method
setMethod("num", "ANY", function(x) x@num)

#' @rdname type-methods
#' @aliases type,Sensor-method
setMethod("type", "Sensor", function(x) x@type)

Resulted file num-methods.Rd.

\name{num}
\alias{num}
\alias{num,ANY-method}
\title{Method num.}
\description{
  Method num.
}

Rsulted file type-methods.Rd.

\name{type}
\alias{type}
\alias{type,Sensor-method}
\title{Method type.}
\description{
  Method type.
}

Methods in one file of the class

Part 1: setGeneric

#' Method csd.
#' @name Sensor-class
#' @rdname Sensor-class
#' @exportMethod csd
setGeneric("csd", function(x) standardGeneric("csd"))

#' Method ssd.
#' @name Sensor-class
#' @rdname Sensor-class
#' @exportMethod ssd
setGeneric("ssd", function(x) standardGeneric("ssd"))

#' Method dsd.
#' @name Sensor-class
#' @rdname Sensor-class
#' @exportMethod dsd
setGeneric("dsd", function(x) standardGeneric("dsd"))

Part 2: setMethod

#' @rdname Sensor-class
#' @aliases csd,Sensor-method
setMethod("csd", "Sensor", function(x) x@csd)

#' @rdname Sensor-class
#' @aliases ssd,Sensor-method
setMethod("ssd", "Sensor", function(x) x@ssd)

#' @rdname Sensor-class
#' @aliases dsd,Sensor-method
setMethod("dsd", "Sensor", function(x) x@dsd)

Resulted file Sensor-class.Rd.

\name{Sensor-class}
\alias{Sensor}
\alias{Sensor-class}
\alias{csd}
\alias{csd,Sensor-method}
\alias{dsd}
\alias{dsd,Sensor-method}
\alias{ssd}
\alias{ssd,Sensor-method}
\title{Method csd.}
\usage{
  Sensor(...)
}
\arguments{
  \item{...}{constructor parameters.}
}
\description{
  Method csd.

  Method ssd.

  Method dsd.

  Class \code{Sensor} defines a gas sensor device.

  Constructor method of Sensor Class.

  Wrapper function Sensor.
}