From spluque at gmail.com  Fri Sep 17 01:24:02 2010
From: spluque at gmail.com (Seb)
Date: Thu, 16 Sep 2010 18:24:02 -0500
Subject: [Rd] S4 plot generic documentation
Message-ID: <87zkvhqnl9.fsf@kolob.sebmags.homelinux.org>

Hi,

Say we want to supply a generic plot() in a package with a simple class,
like this:

---<--------------------cut here---------------start------------------->---
setClass("track",
         representation=representation(x="numeric", y="numeric"))

if (!isGeneric("plot")) {
    setGeneric("plot",
               function(x, y, ...) standardGeneric("plot"))
}

setMethod("plot", signature(x="track", y="missing"),
          function(x, y, ...) {
              plot(x at x, x at y, ...)
          })
---<--------------------cut here---------------end--------------------->---

To document the new method, I thought argument 'y' shouldn't need to be
documented in the package because it's declared 'missing', and the
following in plot-methods.Rd would be ok:

---<--------------------cut here---------------start------------------->---
\name{plot-methods}
\docType{methods}
\alias{plot-methods}
\alias{plot}
\alias{plot,track,missing-method}
\title{Methods}
\description{A plotting method}
\usage{\S4method{plot}{track,missing}(x, \ldots)}
\arguments{
  \item{x}{track.}
  \item{\ldots}{Arguments passed to \code{\link{plot}}.}
}
\section{Methods}{
  \describe{
    \item{plot}{\code{signature(x="track", y="missing")}: some plot.}
  }
}
\keyword{methods}
---<--------------------cut here---------------end--------------------->---

yet 'R CMD check' issues a warning:

---<--------------------cut here---------------start------------------->---
Codoc mismatches from documentation object 'plot-methods':
\S4method{plot}{track,missing}
  Code: function(x, y, ...)
  Docs: function(x, ...)
  Argument names in code not in docs:
    y
  Mismatches in argument names:
    Position: 2 Code: y Docs: ...
---<--------------------cut here---------------end--------------------->---

So it seems as if I'm asked to document the generic, not the particular
method.  What am I misunderstanding?  Thanks.

Cheers,

-- 
Seb



[Rd] S4 plot generic documentation
Seb