[Roxygen-commits] r95 - in pkg: . R sandbox tests/runit
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Jul 26 21:01:51 CEST 2008
Author: pcd
Date: 2008-07-26 21:01:51 +0200 (Sat, 26 Jul 2008)
New Revision: 95
Modified:
pkg/R/Rd.R
pkg/R/collate.R
pkg/R/namespace.R
pkg/R/string.R
pkg/README
pkg/sandbox/Rd.R
pkg/tests/runit/runit.Rd.R
Log:
documenting roclets; overridable titles even without names
Modified: pkg/R/Rd.R
===================================================================
--- pkg/R/Rd.R 2008-07-26 04:09:55 UTC (rev 94)
+++ pkg/R/Rd.R 2008-07-26 19:01:51 UTC (rev 95)
@@ -4,17 +4,76 @@
#' @include roclet.R
roxygen()
-#' Make an Rd roclet which parses the given files and writes the Rd
-#' format to standard out (TODO: write to the file designated by
-#' \code{@@name}). Tries to guess \code{@@name} and \code{@@usage} unless
-#' explicitly given.
+#' 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
+#' \cite{Writing R Extensions}
+#' (\url{http://cran.r-project.org/doc/manuals/R-exts.pdf}) for details.
#'
-#' Contains the member function \code{parse} which parses the result
-#' of \code{parse.files}.
+#' The Rd roclet supports the following tags:
#'
-#' If \code{@@title} isn't present, substitutes \code{@@name} or
-#' equivalent.
+#' \tabular{ll}{
+#' Roxygen tag \tab Rd analogue\cr
+#' \code{@@author} \tab \code{author}\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{@@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{@@references} \tab \code{references}\cr
+#' \code{@@return} \tab \code{value}\cr
+#' \code{@@seealso} \tab \code{seealso}\cr
+#' \code{@@title} \tab \code{title}\cr
+#' \code{@@usage} \tab \code{usage}\cr
+#' }
#'
+#' \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{@@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
+#' 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.}
+#' \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{@@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{@@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).}
+#' }
+#'
#' @param subdir directory into which to place the Rd files; if
#' \code{NULL}, standard out.
#' @return Rd roclet
@@ -77,7 +136,7 @@
description,
perl=TRUE)
sentence <- substr(description, r, attr(r, 'match.length'))
- if (is.null.string(sentence))
+ if (length(sentence) == 0 || is.null.string(sentence))
NULL
else {
chars <- nchar(sentence)
@@ -85,7 +144,7 @@
if (last.char == '.' || last.char == '?')
sentence
else
- paste(trim(sentence), '\\dots', sep='')
+ paste(trim(sentence), '...', sep='')
}
}
@@ -98,8 +157,9 @@
parse.title <- function(partitum, name) {
if (!is.null(partitum$title))
partitum$title
- else if (!is.null(partitum$description))
- first.sentence(partitum$description)
+ else if (!is.null(first.sentence <-
+ first.sentence(partitum$description)))
+ first.sentence
else
name
}
@@ -137,11 +197,13 @@
cat(sprintf('Writing %s to %s\n', name, filename))
unlink(filename)
}
- parse.expression('title', parse.title(partitum, name))
parse.expression('name', name)
if (is.null(partitum$aliases))
parse.expression('alias', name)
}
+ if ((!is.null(name) || !is.null(partitum$title)) &&
+ !is.null(title <- parse.title(partitum, name)))
+ parse.expression('title', title)
}
parse.function.name <- function(partitum) {
@@ -219,8 +281,7 @@
pre.parse,
post.parse)
- roclet$register.default.parsers('title',
- 'references',
+ roclet$register.default.parsers('references',
'note',
'author',
'seealso',
Modified: pkg/R/collate.R
===================================================================
--- pkg/R/collate.R 2008-07-26 04:09:55 UTC (rev 94)
+++ pkg/R/collate.R 2008-07-26 19:01:51 UTC (rev 95)
@@ -5,13 +5,25 @@
roxygen()
#' Make collate roclet which parses the given files; topologically
-#' sorting \code{@@include}s and writing a \code{Collate} directive to
+#' sorting \code{@@include}s and writing a \code{Collate:} directive to
#' standard out.
#'
-#' Contains the member function \code{parse} which parses the result
-#' of \code{parse.files}.
+#' Each \code{@@include} tag should specify the filename of one intrapackage
+#' dependency; multiple \code{@@include} tags may be given.
#'
+#' Contains the member function \code{parse} which parses an arbitrary number
+#' of files.
+#'
+#' @seealso \code{\link{make.roclet}}
#' @return Rd roclet
+#' @examples
+#' #' An example source file, example.R
+#' #' @@include roxygen.R
+#' #' @@include collate.R
+#' roxygen()
+#'
+#' roclet <- make.collate.roclet()
+#' \dontrun{roclet$parse('example.R')}
make.collate.roclet <- function() {
vertices <- NULL
Modified: pkg/R/namespace.R
===================================================================
--- pkg/R/namespace.R 2008-07-26 04:09:55 UTC (rev 94)
+++ pkg/R/namespace.R 2008-07-26 19:01:51 UTC (rev 95)
@@ -4,13 +4,63 @@
#' @include string.R
roxygen()
-#' Make a namespace roclet which parses the given files writes a list of
-#' namespace directives to standard out.
+#' Make a namespace roclet which parses the given files and writes a list of
+#' namespace directives to standard out; see \cite{Writing R Extensions}
+#' (\url{http://cran.r-project.org/doc/manuals/R-exts.pdf}) for details.
#'
-#' Contains the member function \code{parse} which parses the result
-#' of \code{parse.files}.
+#' The namespace roclet supports the following tags:
#'
+#' \tabular{ll}{
+#' Roxygen tag \tab \file{NAMESPACE} equivalent\cr
+#' \code{@@export} \tab \code{export}\cr
+#' \code{@@exportClass} \tab \code{exportClasses}\cr
+#' \code{@@exportMethod} \tab \code{exportMethod}\cr
+#' \code{@@exportPattern} \tab \code{exportPattern}\cr
+#' \code{@@S3method} \tab \code{S3method}\cr
+#' \code{@@import} \tab \code{import}\cr
+#' \code{@@importFrom} \tab \code{importFrom}\cr
+#' \code{@@importClassesFrom} \tab \code{importClassesFrom}\cr
+#' \code{@@importMethodsFrom} \tab \code{importMethodsFrom}\cr
+#' }
+#'
+#' \enumerate{
+#' \item{\code{@@export}}{May be specified with or without value;
+#' if unadorned, roxygen will try to guess
+#' the exported value by assignee, \code{setMethod},
+#' \code{setClass}, etc. Otherwise,
+#' \code{@@export f g ...}
+#' translates to
+#' \code{export(f, g, ...)}.}
+#' \item{\code{@@exportClass}}{Overrides \code{setClass}.}
+#' \item{\code{@@exportMethod}}{Overrides \code{setMethod} or \code{setGeneric}.}
+#' \item{\code{@@exportPattern}}{See \dQuote{1.6.2 Registering S3 methods} from
+#' \cite{Writing R Extensions}.}
+#' \item{\code{@@S3method}}{Overrides the export of an S3 method.}
+#' \item{\code{@@import}}{See \dQuote{1.6.1 Specifying imports and exports}
+#' from \cite{Writing R Extensions}.}
+#' \item{\code{@@importFrom}}{See \dQuote{1.6.1 Specifying imports and exports}
+#' from \cite{Writing R Extensions}.}
+#' \item{\code{@@importClassesFrom}}{See \dQuote{1.6.6 Name spaces with formal
+#' classes and methods} from \cite{Writing R
+#' Extensions}.}
+#' \item{\code{@@importMethodsFrom}}{See \dQuote{1.6.6 Name spaces with formal
+#' classes and methods} from \cite{Writing R
+#' Extensions}.}
+#' }
+#'
#' @return Namespace roclet
+#' @examples
+#' #' An example file, example.R, which imports
+#' #' packages foo and bar
+#' #' @@import foo bar
+#' roxygen()
+#'
+#' #' An exportable function
+#' #' @@export
+#' fun <- function() {}
+#'
+#' roclet <- make.namespace.roclet()
+#' \dontrun{roclet$parse('example.R')}
make.namespace.roclet <- function() {
parse.directive <- function(proc, parms)
cat(sprintf('%s(%s)\n', proc, strmap(Identity, ', ', parms)))
Modified: pkg/R/string.R
===================================================================
--- pkg/R/string.R 2008-07-26 04:09:55 UTC (rev 94)
+++ pkg/R/string.R 2008-07-26 19:01:51 UTC (rev 95)
@@ -3,7 +3,7 @@
#' @include list.R
roxygen()
-#' Absense of words
+#' Absence of words
SPACE <- '[[:space:]]+'
#' Anti-anti-words
Modified: pkg/README
===================================================================
--- pkg/README 2008-07-26 04:09:55 UTC (rev 94)
+++ pkg/README 2008-07-26 19:01:51 UTC (rev 95)
@@ -41,6 +41,9 @@
* Edit the R emacs mode to identify roxygen delimiters when filling,
etc.
+* Find a reasonable way to document the inner functions of make.roclet,
+ etc.
+
1.3. BUGS
* parse.formals doesn't distinguish between no default argument and
@@ -50,7 +53,7 @@
desirable?
* first.sentence is fooled by infix periods, whereupon it resorts to
- \dots.
+ `...'.
-----------
* Hail, Hephaistos! Grant skill and weal.
Modified: pkg/sandbox/Rd.R
===================================================================
--- pkg/sandbox/Rd.R 2008-07-26 04:09:55 UTC (rev 94)
+++ pkg/sandbox/Rd.R 2008-07-26 19:01:51 UTC (rev 95)
@@ -1,3 +1,4 @@
+source('../R/roxygen.R')
source('../R/functional.R')
source('../R/list.R')
source('../R/parse.R')
@@ -13,4 +14,7 @@
files <- if (argc > 0) as.list(argv) else FILES
roclet <- make.Rd.roclet()
-do.call(roclet$parse, files)
+## do.call(roclet$parse, files)
+roclet$parse.parsed(parse.text("#' Would be title
+ #' @title Overriden title
+ roxygen()"))
Modified: pkg/tests/runit/runit.Rd.R
===================================================================
--- pkg/tests/runit/runit.Rd.R 2008-07-26 04:09:55 UTC (rev 94)
+++ pkg/tests/runit/runit.Rd.R 2008-07-26 19:01:51 UTC (rev 95)
@@ -33,39 +33,39 @@
test.name.from.assignment <- function()
check.Rd.output('a <- 2',
- output=c('\\title{a}',
- '\\name{a}',
- '\\alias{a}'))
+ output=c('\\name{a}',
+ '\\alias{a}',
+ '\\title{a}'))
test.name.overriding.assignment <- function()
check.Rd.output("#' @name b
a <- 2",
- output=c('\\title{b}',
- '\\name{b}',
- '\\alias{b}'))
+ output=c('\\name{b}',
+ '\\alias{b}',
+ '\\title{b}'))
test.implicit.usage.from.formals <- function()
check.Rd.output("a <- function(a=1) {}",
- output=c("\\title{a}",
- "\\name{a}",
+ output=c("\\name{a}",
"\\alias{a}",
+ "\\title{a}",
"\\usage{a(a=1)}"))
test.explicit.usage <- function()
check.Rd.output("#' @usage a(a=2)
a <- function(a=1) {}",
- output=c("\\title{a}",
- "\\name{a}",
+ output=c("\\name{a}",
"\\alias{a}",
+ "\\title{a}",
"\\usage{a(a=2)}"))
test.params <- function()
check.Rd.output("#' @param a an incipit letter
#' @param z a terminal letter
a <- function(a=1, z=2) {}",
- output=c("\\title{a}",
- "\\name{a}",
+ output=c("\\name{a}",
"\\alias{a}",
+ "\\title{a}",
"\\usage{a(a=1, z=2)}",
"\\arguments{\\item{a}{an incipit letter}",
"\\item{z}{a terminal letter}}"))
@@ -93,15 +93,13 @@
"\\alias{b}"))
test.generic.keys <- function()
- check.Rd.output("#' @title test
- #' @references test
+ check.Rd.output("#' @references test
#' @note test
#' @author test
#' @seealso test
#' @concept test
roxygen()",
- output=c("\\title{test}",
- "\\references{test}",
+ output=c("\\references{test}",
"\\note{test}",
"\\author{test}",
"\\seealso{test}",
@@ -110,26 +108,33 @@
test.title.from.description <- function()
check.Rd.output("#' Description with sentence. That continueth.
a <- 2",
- output=c("\\title{Description with sentence.}",
- "\\name{a}",
+ output=c("\\name{a}",
"\\alias{a}",
+ "\\title{Description with sentence.}",
paste("\\description{Description with sentence.",
"That continueth.}")))
+test.override.title <- function()
+ check.Rd.output("#' Would be title
+ #' @title Overriden title
+ roxygen()",
+ output=c("\\title{Overriden title}",
+ "\\description{Would be title}"))
+
test.question.mark.end.of.sentence <- function()
check.Rd.output("#' Is a number odd?
is.odd <- function(a) {}",
- output=c('\\title{Is a number odd?}',
- '\\name{is.odd}',
+ output=c('\\name{is.odd}',
'\\alias{is.odd}',
+ '\\title{Is a number odd?}',
'\\usage{is.odd(a)}',
'\\description{Is a number odd?}'))
test.ellipsis.on.no.period <- function()
check.Rd.output("#' Whether a number is odd
is.odd <- function(a) {}",
- output=c('\\title{Whether a number is odd\\dots}',
- '\\name{is.odd}',
+ output=c('\\name{is.odd}',
'\\alias{is.odd}',
+ '\\title{Whether a number is odd...}',
'\\usage{is.odd(a)}',
'\\description{Whether a number is odd}'))
More information about the Roxygen-commits
mailing list