% File src/library/methods/man/promptClass.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2016 R Core Team
% Distributed under GPL 2 or later

\name{promptClass}
\alias{promptClass}
\title{Generate a Shell for Documentation of a Formal Class}
\description{
  Assembles all relevant slot and method information for a class, with
  minimal markup for Rd processing; no QC facilities at present.
}
\usage{
promptClass(clName, filename = NULL, type = "class",
            keywords = "classes", where = topenv(parent.frame()),
            generatorName = clName)
}
\arguments{
  \item{clName}{a character string naming the class to be documented.}
  \item{filename}{usually, a connection or a character string giving the
    name of the file to which the documentation shell should be written.
    The default corresponds to a file whose name is the topic name for
    the class documentation, followed by \code{".Rd"}.  Can also be
    \code{NA} (see below).}
  \item{type}{the documentation type to be declared in the output file.}
  \item{keywords}{the keywords to include in the shell of the
    documentation.  The keyword \code{"classes"} should be one of
    them.}
  \item{where}{where to look for the definition of the class and of
    methods that use it.
    %%FIXME: By default, anywhere in the current search list.
  }
  \item{generatorName}{the name for a generator function for this
    class; only required if a generator function was created
    \emph{and} saved under a name different from the class name.
  }
}
\details{
  The class definition is found on the search list.  Using that
  definition, information about classes extended and slots is
  determined.

  In addition, the currently available generics with methods for this
  class are found (using \code{\link{getGenerics}}).  Note that these
  methods need not be in the same environment as the class definition; in
  particular, this part of the output may depend on which packages are
  currently in the search list.

  As with other prompt-style functions, unless \code{filename} is
  \code{NA}, the documentation shell is written to a file, and a message
  about this is given.  The file will need editing to give information
  about the \emph{meaning} of the class.  The output of
  \code{promptClass} can only contain information from the metadata
  about the formal definition and how it is used.

  If \code{filename} is \code{NA}, a list-style representation of the
  documentation shell is created and returned.  Writing the shell to a
  file amounts to \code{cat(unlist(x), file = filename, sep = "\\n")},
  where \code{x} is the list-style representation.

  If a generator function is found assigned under the class name or
  the optional \code{generatorName}, skeleton documentation for that
  function is added to the file.
}
\value{
  If \code{filename} is \code{NA}, a list-style representation of the
  documentation shell.  Otherwise, the name of the file written to is
  returned invisibly.
}
\author{
  VJ Carey \email{stvjc@channing.harvard.edu} and John Chambers
}
\references{
 Chambers, John M. (2008)
 \emph{Software for Data Analysis: Programming with R}
  Springer.  (For the R version.)

 Chambers, John M. (1998)
 \emph{Programming with Data}
 Springer (For the original S4 version.)
}
\seealso{
  \code{\link{prompt}} for documentation of functions,
  \code{\link{promptMethods}} for documentation of method definitions.

  For processing of the edited documentation, either use
  \code{R CMD \link{Rdconv}},
  or include the edited file in the \file{man} subdirectory of a
  package.
}
\examples{
\dontshow{
## from setClass
## A simple class with two slots
setClass("track",
         slots = c(x="numeric", y="numeric"))
## A class extending the previous, adding one more slot
setClass("trackCurve", contains = "track",
         slots = c(smooth = "numeric"))
## A class similar to "trackCurve", but with different structure
## allowing matrices for the "y" and "smooth" slots
setClass("trackMultiCurve",
         slots = c(x="numeric", y="matrix", smooth="matrix"),
         prototype = list(x=numeric(), y=matrix(0,0,0), smooth= matrix(0,0,0)))

setIs("trackMultiCurve", "trackCurve",
  test = function(obj) {ncol(slot(obj, "y")) == 1},
  coerce = function(obj) { new("trackCurve", x = slot(obj, "x"),
        y = as.numeric(slot(obj,"y")), smooth = as.numeric(slot(obj, "smooth")))})

## from setMethod
require(graphics)

setMethod("plot", "track",
 function(x, y, ...) plot(slot(x, "y"), y,  ...)
)
setMethod("plot", c("trackCurve", "missing"),
function(x, y, ...) {
  plot(as(x, "track"))
  if(length(slot(x, "smooth") > 0))
    lines(slot(x, "x"), slot(x, "smooth"))
  }
)

promptClass("trackMultiCurve", stdout())

promptClass("track", stdout())
}
\dontrun{> promptClass("track")
A shell of class documentation has been written to the
file "track-class.Rd".
}
\dontshow{removeMethods("plot")
}}

\keyword{programming}
\keyword{classes}