[Roxygen-commits] r189 - in pkg: R inst/doc inst/doc/pseudoprime inst/doc/pseudoprime/R
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Aug 26 14:38:35 CEST 2008
Author: pcd
Date: 2008-08-26 14:38:34 +0200 (Tue, 26 Aug 2008)
New Revision: 189
Added:
pkg/inst/doc/pseudoprime/
pkg/inst/doc/pseudoprime/DESCRIPTION
pkg/inst/doc/pseudoprime/R/
pkg/inst/doc/pseudoprime/R/pseudoprime-package.R
pkg/inst/doc/pseudoprime/R/pseudoprime.R
Removed:
pkg/inst/doc/pseudoprime-package.R
pkg/inst/doc/pseudoprime.R
Modified:
pkg/R/callgraph.R
pkg/inst/doc/hello-roxygen.R
pkg/inst/doc/roxygen.Rnw
Log:
expound upon pseudoprime package
Modified: pkg/R/callgraph.R
===================================================================
--- pkg/R/callgraph.R 2008-08-26 12:38:31 UTC (rev 188)
+++ pkg/R/callgraph.R 2008-08-26 12:38:34 UTC (rev 189)
@@ -18,9 +18,9 @@
#'
#' \enumerate{
#' \item{\code{@@callGraph}}{Create a call graph of the default
-#' depth (currently 2), excluding primitive functions.}
+#' depth, excluding primitive functions.}
#' \item{\code{@@callGraphPrimitives}}{Create a call graph of the
-#' default depth (currently 2), including primitive functions.}
+#' default depth, including primitive functions.}
#' \item{\code{@@callGraphDepth}}{Change the depth of the callgraph
#' from the default of 2.}
#' }
Modified: pkg/inst/doc/hello-roxygen.R
===================================================================
--- pkg/inst/doc/hello-roxygen.R 2008-08-26 12:38:31 UTC (rev 188)
+++ pkg/inst/doc/hello-roxygen.R 2008-08-26 12:38:34 UTC (rev 189)
@@ -2,5 +2,4 @@
#'
#' @name helloRoxygen-package
#' @docType package
-#' @import roxygen
-roxygen()
+NA
Added: pkg/inst/doc/pseudoprime/DESCRIPTION
===================================================================
--- pkg/inst/doc/pseudoprime/DESCRIPTION (rev 0)
+++ pkg/inst/doc/pseudoprime/DESCRIPTION 2008-08-26 12:38:34 UTC (rev 189)
@@ -0,0 +1,13 @@
+Package: pseudoprime
+Type: Package
+Title: Pseudoprimality with Fermat's little theorem
+Version: 0.1
+Date: 2008-08-24
+Author: Peter Danenberg <pcd at roxygen.org>
+Maintainer: Peter Danenberg <pcd at roxygen.org>
+Description: A probabilistic primality test using Fermat's little
+ theorem that is fooled every time by Carmichael numbers.
+License: GPL (>= 2)
+LazyLoad: yes
+Depends: roxygen
+Collate: 'pseudoprime-package.R' 'pseudoprime.R'
Copied: pkg/inst/doc/pseudoprime/R/pseudoprime-package.R (from rev 188, pkg/inst/doc/pseudoprime-package.R)
===================================================================
--- pkg/inst/doc/pseudoprime/R/pseudoprime-package.R (rev 0)
+++ pkg/inst/doc/pseudoprime/R/pseudoprime-package.R 2008-08-26 12:38:34 UTC (rev 189)
@@ -0,0 +1,30 @@
+#' Tests pseudoprimality by Fermat's little theorem.
+#'
+#' \tabular{ll}{
+#' Package: \tab pseudoprime\cr
+#' Type: \tab Package\cr
+#' Version: \tab 0.1\cr
+#' Date: \tab 2008-08-24\cr
+#' License: \tab GPL (>= 2)\cr
+#' LazyLoad: \tab yes\cr
+#' }
+#'
+#' Using the Fermat primality test, pseudoprime checks for primes
+#' probabilistically; the test is fooled every time by Carmichael
+#' numbers.
+#'
+#' \code{\link{is.pseudoprime}} checks a number \code{n} for
+#' pseudoprimality, applying Fermat's test \code{times} times.
+#'
+#' @name pseudoprime-package
+#' @aliases pseudoprime
+#' @docType package
+#' @title Tests pseudoprimality by Fermat's little theorem
+#' @author Peter Danenberg \email{pcd@@roxygen.org}
+#' @references
+#' \url{http://en.wikipedia.org/wiki/Fermat's_little_theorem}
+#' @keywords package
+#' @seealso \code{\link{is.pseudoprime}}
+#' @examples
+#' is.pseudoprime(13, 4)
+roxygen()
Copied: pkg/inst/doc/pseudoprime/R/pseudoprime.R (from rev 188, pkg/inst/doc/pseudoprime.R)
===================================================================
--- pkg/inst/doc/pseudoprime/R/pseudoprime.R (rev 0)
+++ pkg/inst/doc/pseudoprime/R/pseudoprime.R 2008-08-26 12:38:34 UTC (rev 189)
@@ -0,0 +1,44 @@
+#' Test an integer for primality with Fermat's Little Theorem.
+#'
+#' Fermat's Little Theorem states that if \eqn{n} is a prime
+#' number and \eqn{a} is any positive integer less than \eqn{n},
+#' then \eqn{a} raised to the \eqn{n}th power is congruent to
+#' \eqn{a\ modulo\ n}{a modulo n}.
+#'
+#' @author Peter Danenberg \email{pcd@@roxygen.org}
+#' @param n the integer to test for primality
+#' @return Whether the integer passes the Fermat test
+#' for a randomized \eqn{0 < a < n}
+#' @callGraphPrimitives
+#' @note \code{fermat.test} doesn't work for integers above
+#' approximately fifteen because modulus loses precision.
+fermat.test <- function(n) {
+ a <- floor(runif(1, min=1, max=n))
+ a ^ n %% n == a
+}
+
+#' Check an integer for pseudo-primality to an arbitrary
+#' precision.
+#'
+#' A number is pseudo-prime if it is probably prime, the basis
+#' of which is the probabilistic Fermat test; if it passes two
+#' such tests, the chances are better than 3 out of 4 that
+#' \eqn{n} is prime.
+#'
+#' @author Peter Danenberg \email{pcd@@roxygen.org}
+#' @param n the integer to test for pseudoprimality.
+#' @param times the number of Fermat tests to perform
+#' @return Whether the number is pseudoprime
+#' @export
+#' @seealso \code{\link{fermat.test}}
+#' @references Abelson, Hal; Jerry Sussman, and Julie Sussman.
+#' Structure and Interpretation of Computer Programs.
+#' Cambridge: MIT Press, 1984.
+#' @examples
+#' # TRUE most of the time
+#' is.pseudoprime(13, 4)
+is.pseudoprime <- function(n, times) {
+ if (times == 0) TRUE
+ else if (fermat.test(n)) is.pseudoprime(n, times - 1)
+ else FALSE
+}
Deleted: pkg/inst/doc/pseudoprime-package.R
===================================================================
--- pkg/inst/doc/pseudoprime-package.R 2008-08-26 12:38:31 UTC (rev 188)
+++ pkg/inst/doc/pseudoprime-package.R 2008-08-26 12:38:34 UTC (rev 189)
@@ -1,34 +0,0 @@
-#' Tests pseudoprimality by Fermat's Little Theorem.
-#'
-#' \tabular{ll}{
-#' Package: \tab pseudoprime\cr
-#' Type: \tab Package\cr
-#' Version: \tab 1.0\cr
-#' Date: \tab 2008-08-24\cr
-#' License: \tab What license is it under?\cr
-#' LazyLoad: \tab yes\cr
-#' }
-#'
-#' Using the Fermat primality test, pseudoprime checks for primes
-#' probabilistically; the test is fooled every time by Carmichael
-#' numbers.
-#'
-#' \code{\link{is.pseudoprime}} checks a number \code{n} for
-#' pseudoprimality, applying Fermat's test \code{times} times.
-#'
-#' @name pseudoprime-package
-#' @aliases pseudoprime
-#' @docType package
-#' @title Tests pseudoprimality by Fermat's Little Theorem
-#' @author Peter Danenberg \email{pcd@@roxygen.org}
-#' @references
-#' \url{http://en.wikipedia.org/wiki/Fermat's_little_theorem}
-#'
-#' \url{http://en.wikipedia.org/wiki/Fermat_primality_test}
-#'
-#' \url{http://en.wikipedia.org/wiki/Carmichael_number}
-#' @keywords package
-#' @seealso \code{\link{is.pseudoprime}}
-#' @examples
-#' is.pseudoprime(13, 4)
-roxygen()
Deleted: pkg/inst/doc/pseudoprime.R
===================================================================
--- pkg/inst/doc/pseudoprime.R 2008-08-26 12:38:31 UTC (rev 188)
+++ pkg/inst/doc/pseudoprime.R 2008-08-26 12:38:34 UTC (rev 189)
@@ -1,43 +0,0 @@
-#' Test an integer for primality with Fermat's Little Theorem.
-#'
-#' Fermat's Little Theorem states that if \eqn{n} is a prime
-#' number and \eqn{a} is any positive integer less than \eqn{n},
-#' then \eqn{a} raised to the \eqn{n}th power is congruent to
-#' \eqn{a modulo n}.
-#'
-#' @author Peter Danenberg \email{pcd@@roxygen.org}
-#' @param n the integer to test for primality
-#' @return Whether the integer passes the Fermat test
-#' for a randomized \eqn{0 < a < n}
-#' @note \code{fermat.test} doesn't work for integers above
-#' approximately fifteen because modulus loses precision.
-fermat.test <- function(n) {
- a <- floor(runif(1, min=1, max=n))
- a ^ n %% n == a
-}
-
-#' Check an integer for pseudo-primality to an arbitrary
-#' precision.
-#'
-#' A number is pseudo-prime if it is probably prime, the basis
-#' of which is the probabilistic Fermat test; if it passes two
-#' such tests, the chances are better than 3 out of 4 that
-#' \eqn{n} is prime.
-#'
-#' @author Peter Danenberg \email{pcd@@roxygen.org}
-#' @param n the integer to test for pseudoprimality.
-#' @param times the number of Fermat tests to perform
-#' @return Whether the number is pseudoprime
-#' @export
-#' @seealso \code{\link{fermat.test}}
-#' @references Abelson, Hal; Jerry Sussman, and Julie Sussman.
-#' Structure and Interpretation of Computer Programs.
-#' Cambridge: MIT Press, 1984.
-#' @keywords pseudoprime fermat
-#' @examples
-#' is.pseudoprime(13, 4) # TRUE most of the time
-is.pseudoprime <- function(n, times) {
- if (times == 0) TRUE
- else if (fermat.test(n)) is.pseudoprime(n, times - 1)
- else FALSE
-}
Modified: pkg/inst/doc/roxygen.Rnw
===================================================================
--- pkg/inst/doc/roxygen.Rnw 2008-08-26 12:38:31 UTC (rev 188)
+++ pkg/inst/doc/roxygen.Rnw 2008-08-26 12:38:34 UTC (rev 189)
@@ -1,17 +1,20 @@
\documentclass{article}
+\usepackage[utf8]{inputenc}
\usepackage{fancyvrb}
\usepackage{url}
+\usepackage{graphicx}
+\usepackage{grffile}
%% \VignetteIndexEntry{Roxygen Vignette}
\newcommand{\Roxygen}{\texttt{Roxygen}}
-%% filename, caption, label
-\newcommand{\listing}[3]{ %
+%% path, filename, caption, label
+\newcommand{\listing}[4]{ %
\begin{figure}[h] %
\centering %
\VerbatimInput[numbers=left, %
frame=single, %
- label=#1]{#1} %
- \caption{#2} %
- \label{#3} %
+ label=#2]{#1} %
+ \caption{#3} %
+ \label{#4} %
\end{figure} %
}
\author{Peter Danenberg \url{<pcd at roxygen.org>}}
@@ -30,14 +33,15 @@
\end{itemize}
\end{abstract}
\tableofcontents
-\section{Minimal example}
+\section{Minimal Example: ``Hello Roxygen''}
\listing{hello-roxygen.R}
- {Roxygen sanity-check \texttt{hello-roxygen.R}}
+ {hello-roxygen.R}
+ {Roxygen sanity-check}
{hello-roxygen}
A minimal example that serves as a sanity check is found in
-\texttt{hello-roxygen.R} (see Figure \ref{hello-roxygen}). It merely
+\texttt{hello-roxygen.R} (see figure \ref{hello-roxygen}). It merely
replaces the package description so that `\texttt{R CMD check}' will run
after \Roxygen{} has processed the package skeleton:
@@ -54,14 +58,67 @@
@
A new \texttt{helloRoxygen/man/helloRoxygen-package.Rd} should have
-been created with the contents of Figure \ref{hello-roxygen}; and
+been created with the contents of figure \ref{hello-roxygen}; and
`\texttt{R CMD check helloRoxygen}' should terminate successfully.
-\section{Detailed example}
+\section{Example: Pseudoprimality}
+\subsection{Package Description}
-Forthcoming . . .
+\listing{pseudoprime/R/pseudoprime-package.R}
+ {pseudoprime-package.R}
+ {Package description for \texttt{pseudoprime}}
+ {pseudoprime-package}
-\listing{pseudoprime.R}
+One could imagine, for instance, a less trivial package that actually
+does something; enter \texttt{pseudoprime}, a toy that tests for
+primes using Fermat's little
+theorem.\footnote{\url{http://en.wikipedia.org/wiki/Fermat's_little_theorem}}
+
+A package description has been provided in figure
+\ref{pseudoprime-package}; notice the \texttt{roxygen()} statement in
+line 30: each \Roxygen{} description block must be followed by a
+statement, even header material that describes a file or package in
+lieu of a specific function. \texttt{roxygen()} is provided as a
+\texttt{NOOP} (null statement) to stand in for such cases.
+
+The first sentence of any \Roxygen{} block briefly describes its
+object; and may be followed directly by a \Roxygen{} tag (as in figure
+\ref{hello-roxygen}) or a more detailed description (as in figure
+\ref{pseudoprime-package}). The detailed description begins after the
+intervening blank line (line 2) and continues until the first
+\Roxygen{} tag (line 19).
+
+Each \Roxygen{} tag begins with an ampersand, like \texttt{@name},
+\texttt{@author}, etc.; which means, incidentally, that all real
+ampersands have to be escaped with a double-ampersand, as in
+\verb=\email{pcd@@wikitex.org}= (line 23).
+
+Furthermore, although \Roxygen{} tags replace many of the structural
+Rd elements such as \verb=\title=, \verb=\keyword=, etc.; many of the
+stylistic Rd elements such as \verb=\emph= and \verb=\email= can be
+used freely within \Roxygen{} tags. See ``Writing R Extensions'' for
+details.
+
+\subsection{Source Code}
+
+\listing{pseudoprime/R/pseudoprime.R}
+ {pseudoprime.R}
{Roxygen example \texttt{pseudoprime.R}}
{pseudoprime}
+
+<<>>=
+roxygenize('pseudoprime',
+ roxygen.dir='pseudoprime',
+ copy.package=FALSE,
+ unlink.target=FALSE)
+
+@
+
+
+\begin{figure}
+\centering
+\includegraphics{pseudoprime/inst/doc/fermat.test-callgraph}
+\caption{\texttt{fermat.test} call graph with primitives}
+\label{fermat-test}
+\end{figure}
\end{document}
More information about the Roxygen-commits
mailing list