[Roxygen-commits] r97 - in pkg: R tests/runit
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Jul 26 23:27:56 CEST 2008
Author: pcd
Date: 2008-07-26 23:27:55 +0200 (Sat, 26 Jul 2008)
New Revision: 97
Modified:
pkg/R/Rd.R
pkg/tests/runit/runit.Rd.R
Log:
more Rd docs
Modified: pkg/R/Rd.R
===================================================================
--- pkg/R/Rd.R 2008-07-26 19:02:03 UTC (rev 96)
+++ pkg/R/Rd.R 2008-07-26 21:27:55 UTC (rev 97)
@@ -5,24 +5,26 @@
roxygen()
#' Make an Rd roclet which parses the given files and, if specified, populates
-#' the given subdirectory with Rd files; or writes the to standard out. See
+#' the given subdirectory with Rd files; or writes to standard out. See
#' \cite{Writing R Extensions}
#' (\url{http://cran.r-project.org/doc/manuals/R-exts.pdf}) for details.
#'
-#' The Rd roclet supports the following tags:
+#' The first paragraph of a roxygen block constitutes its description, the
+#' subsequent paragraphs its details; moreover, the Rd roclet supports these
+#' tags:
#'
#' \tabular{ll}{
#' Roxygen tag \tab Rd analogue\cr
#' \code{@@author} \tab \code{\\author}\cr
-#' \code{@@aliases} \tab \code{\\alias}\cr
+#' \code{@@aliases} \tab \code{\\alias, ...}\cr
#' \code{@@concept} \tab \code{\\concept}\cr
#' \code{@@example} \tab \emph{n/a}\cr
#' \code{@@examples} \tab \code{\\examples}\cr
-#' \code{@@keywords} \tab \code{\\keyword}\cr
+#' \code{@@keywords} \tab \code{\\keyword, ...}\cr
#' \code{@@method} \tab \code{\\method}\cr
#' \code{@@name} \tab \code{\\name}\cr
#' \code{@@note} \tab \code{\\note}\cr
-#' \code{@@param} \tab \code{\\arguments{\\item{} ...}}\cr
+#' \code{@@param} \tab \code{\\arguments{\\item, ...}}\cr
#' \code{@@references} \tab \code{\\references}\cr
#' \code{@@return} \tab \code{\\value}\cr
#' \code{@@seealso} \tab \code{\\seealso}\cr
@@ -33,42 +35,45 @@
#' \enumerate{
#' \item{\code{@@author}}{See \dQuote{2.1.1 Documenting functions} from
#' \cite{Writing R Extensions}.}
-#' \item{\code{@@aliases}}{\code{@@alias a b ...} translates to \code{\alias{a}},
-#' \code{\alias{b}}, \code{\alias{...}}, &c. A default
-#' alias is normally plucked from the \code{@@name} or
-#' assignee; but if you specify one alias, specify them
-#' all.}
+#' \item{\code{@@aliases}}{A default alias is plucked from the \code{@@name} or
+#' assignee; otherwise, \code{@@alias a b ...} translates
+#' to \code{\alias{a}}, \code{\alias{b}}, &c.
+#'
+#' If you specify one alias, however, specify them all.}
#' \item{\code{@@concept}}{See \dQuote{2.8 Indices} from
#' \cite{Writing R Extensions}.}
#' \item{\code{@@example}}{Each \code{@@example} tag specifies an example file
#' relative to the package head; if the file resides in
#' \file{tests}, for instance, it will be checked with
-#' \command{R CMD check}. The contents of each file will
+#' \command{R CMD check}.
+#'
+#' The contents of the file will
#' be concatenated under \code{\examples{...}}.}
#' \item{\code{@@examples}}{Verbatim examples; see \dQuote{2.1.1
#' Documenting functions} from \cite{Writing R
#' Extensions}.}
#' \item{\code{@@keywords}}{\code{@@keywords a b ...} translates to
-#' \code{\keyword{a}}, \code{\keyword{b}},
-#' \code{\keyword{...}}, &c.}
-#' \item{\code{@@method}}{\code{@@method <generic> <class>} is used to
-#' document S3 functions.}
-#' \item{\code{@@name}}{In the absense of \code{@@name}, the name of an
-#' assignment is plucked from the assignee.}
+#' \code{\keyword{a}}, \code{\keyword{b}}, &c.}
+#' \item{\code{@@method}}{Use \code{@@method <generic> <class>} to document
+#' S3 functions.}
+#' \item{\code{@@name}}{In the absense of an explicit \code{@@name} tag, the
+#' name of an assignment is plucked from the assignee.}
#' \item{\code{@@note}}{See \dQuote{2.1.1 Documenting functions} from
#' \cite{Writing R Extensions}.}
-#' \item{\code{@@param}}{Each parameter of the documented function should
-#' specify \code{@@param <variable> <description>}; `...'
-#' becomes \\dots.}
+#' \item{\code{@@param}}{Each function variable should have a
+#' \code{@@param <variable> <description>} specified.}
#' \item{\code{@@references}}{See \dQuote{2.1.1 Documenting functions} from
#' \cite{Writing R Extensions}.}
#' \item{\code{@@return}}{The return value of the function, or \code{NULL}.}
#' \item{\code{@@seealso}}{See \dQuote{2.1.1 Documenting functions} from
#' \cite{Writing R Extensions}.}
-#' \item{\code{@@title}}{A default title is plucked from the first phrase
-#' of the description ending with a period, question
-#' mark or newline; otherwise, from the \code{@@name}
-#' or assignee. It can be overridden with \code{@@title}.}
+#' \item{\code{@@title}}{A default title is plucked from the first sentence
+#' of the description; that is, the first phrase ending
+#' with a period, question mark or newline.
+#'
+#' In the absence of a description, the title becomes
+#' the \code{@@name} or assignee; lastly, it can be
+#' overridden with \code{@@title}.}
#' \item{\code{@@usage}}{A default usage is construed from a function's formals,
#' but can be overridden with \code{@@usage} (e.g. in the case
#' of multiple functions in one Rd unit).}
@@ -77,6 +82,29 @@
#' @param subdir directory into which to place the Rd files; if
#' \code{NULL}, standard out.
#' @return Rd roclet
+#' @examples
+#' #' This sentence describes the function.
+#' #'
+#' #' Here are the details (notice the blank line);
+#' #' the name, title, usage and alias will be
+#' #' automatically generated.
+#' #'
+#' #' @@param a a parameter
+#' #' @@return NULL
+#' f <- function(a=1) NULL
+#'
+#' #' S3 function's require a @@method tag for
+#' #' the time being.
+#' #'
+#' #' @@method specialize foo
+#' #' @@param f a generic foo
+#' #' @@param ... ignored
+#' #' @@return The specialized foo
+#' specialize.foo <- function(f, ...)
+#' actually.specialize(f)
+#'
+#' roclet <- make.Rd.roclet('man')
+#' \dontrun{roclet$parse('example.R')}
make.Rd.roclet <- function(subdir=NULL) {
#' Translate a key and expressions into an Rd expression;
#' multiple expressions take their own braces.
Modified: pkg/tests/runit/runit.Rd.R
===================================================================
--- pkg/tests/runit/runit.Rd.R 2008-07-26 19:02:03 UTC (rev 96)
+++ pkg/tests/runit/runit.Rd.R 2008-07-26 21:27:55 UTC (rev 97)
@@ -116,9 +116,9 @@
test.override.title <- function()
check.Rd.output("#' Would be title
- #' @title Overriden title
+ #' @title Overridden title
roxygen()",
- output=c("\\title{Overriden title}",
+ output=c("\\title{Overridden title}",
"\\description{Would be title}"))
test.question.mark.end.of.sentence <- function()
More information about the Roxygen-commits
mailing list