[Roxygen-commits] r191 - in pkg/inst/doc: . pseudoprime pseudoprime/R
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Aug 26 20:20:24 CEST 2008
Author: pcd
Date: 2008-08-26 20:20:24 +0200 (Tue, 26 Aug 2008)
New Revision: 191
Added:
pkg/inst/doc/pseudoprime/R/fermat.R
Modified:
pkg/inst/doc/hello-roxygen.R
pkg/inst/doc/pseudoprime/DESCRIPTION
pkg/inst/doc/pseudoprime/R/pseudoprime.R
pkg/inst/doc/roxygen.Rnw
Log:
expound upon fermat test; break up pseudoprime.R
Modified: pkg/inst/doc/hello-roxygen.R
===================================================================
--- pkg/inst/doc/hello-roxygen.R 2008-08-26 18:20:20 UTC (rev 190)
+++ pkg/inst/doc/hello-roxygen.R 2008-08-26 18:20:24 UTC (rev 191)
@@ -1,4 +1,4 @@
-#' A toy package to check Roxygen's sanity
+#' A package to check Roxygen's sanity
#' @name helloRoxygen-package
#' @docType package
NA
Modified: pkg/inst/doc/pseudoprime/DESCRIPTION
===================================================================
--- pkg/inst/doc/pseudoprime/DESCRIPTION 2008-08-26 18:20:20 UTC (rev 190)
+++ pkg/inst/doc/pseudoprime/DESCRIPTION 2008-08-26 18:20:24 UTC (rev 191)
@@ -10,4 +10,4 @@
License: GPL (>= 2)
LazyLoad: yes
Depends: roxygen
-Collate: 'pseudoprime-package.R' 'pseudoprime.R'
+Collate: 'fermat.R' 'pseudoprime-package.R' 'pseudoprime.R'
Added: pkg/inst/doc/pseudoprime/R/fermat.R
===================================================================
--- pkg/inst/doc/pseudoprime/R/fermat.R (rev 0)
+++ pkg/inst/doc/pseudoprime/R/fermat.R 2008-08-26 18:20:24 UTC (rev 191)
@@ -0,0 +1,20 @@
+#' 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}.
+#'
+#' @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.
+#' @references
+#' \url{http://en.wikipedia.org/wiki/Fermat's_little_theorem}
+#' @author Peter Danenberg \email{pcd@@roxygen.org}
+fermat.test <- function(n) {
+ a <- floor(runif(1, min=1, max=n))
+ a ^ n %% n == a
+}
Modified: pkg/inst/doc/pseudoprime/R/pseudoprime.R
===================================================================
--- pkg/inst/doc/pseudoprime/R/pseudoprime.R 2008-08-26 18:20:20 UTC (rev 190)
+++ pkg/inst/doc/pseudoprime/R/pseudoprime.R 2008-08-26 18:20:24 UTC (rev 191)
@@ -1,21 +1,5 @@
-#' 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}.
-#'
-#' @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.
-#' @author Peter Danenberg \email{pcd@@roxygen.org}
-fermat.test <- function(n) {
- a <- floor(runif(1, min=1, max=n))
- a ^ n %% n == a
-}
+#' @include fermat.R
+roxygen()
#' Check an integer for pseudo-primality to an arbitrary
#' precision.
Modified: pkg/inst/doc/roxygen.Rnw
===================================================================
--- pkg/inst/doc/roxygen.Rnw 2008-08-26 18:20:20 UTC (rev 190)
+++ pkg/inst/doc/roxygen.Rnw 2008-08-26 18:20:24 UTC (rev 191)
@@ -4,13 +4,13 @@
\usepackage{url}
\usepackage{graphicx}
\usepackage{grffile}
-\usepackage{afterpage}
+%% \usepackage{afterpage}
\usepackage{float}
%% \VignetteIndexEntry{Roxygen Vignette}
\newcommand{\Roxygen}{\texttt{Roxygen}}
%% path, filename, caption, label
\newcommand{\listing}[4]{ %
- \begin{figure}[ht] %
+ \begin{figure}[H] %
\centering %
\VerbatimInput[numbers=left, %
frame=single, %
@@ -26,7 +26,7 @@
\begin{abstract}
The purpose of the \Roxygen{} Vignette is to show how to get up and
running with \Roxygen{}; for details, including a complete list of
- tags, consult the help pages for:
+ tags, consult the help pages or manual for:
\begin{itemize}
\item \texttt{make.callgraph.roclet}
\item \texttt{make.collate.roclet}
@@ -42,10 +42,10 @@
{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
-replaces the package description so that `\texttt{R CMD check}' will run
-after \Roxygen{} has processed the package skeleton:
+\texttt{hello-roxygen.R} (fig. \ref{hello-roxygen}) is a minimal
+example to check the sanity of your local \Roxygen{} installation. It
+merely replaces the package description so that `\texttt{R CMD check}'
+will run after \Roxygen{} has processed the package skeleton:
<<keep.source=true>>=
library(roxygen)
@@ -64,6 +64,7 @@
`\texttt{R CMD check helloRoxygen}' should terminate successfully.
\section{Example: Pseudoprimality}
+
\subsection{Package Description}
\listing{pseudoprime/R/pseudoprime-package.R}
@@ -100,21 +101,46 @@
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.
+details. [TODO: bibtex reference]
-\subsection{Source Code}
+\subsection{Fermat Test}
+\listing{pseudoprime/R/fermat.R}
+ {fermat.R}
+ {Roxygen example \texttt{fermat.R}}
+ {fermat}
+
+When documenting functions (fig. \ref{fermat}), every parameter must
+be documented with a \texttt{@param} tag (line 8); which consists of
+\texttt{@param <variable> <description>}. Similarly, the return value
+must be documented with \texttt{@return <description>} (lines 9-10).
+
+Notice \texttt{@callGraphPrimitives} on line 11: it creates a call
+graph at the default depth similar to figure \ref{fermat-test},
+including primitive functions; \texttt{@callGraph}, on the other hand,
+would exclude primitive functions.
+
+\begin{figure}[H]
+ \centering
+ \includegraphics{pseudoprime/inst/doc/fermat.test-callgraph}
+ \caption{\texttt{fermat.test} call graph with primitives}
+ \label{fermat-test}
+\end{figure}
+
+\subsection{Pseudoprime}
+
\listing{pseudoprime/R/pseudoprime.R}
{pseudoprime.R}
{Roxygen example \texttt{pseudoprime.R}}
{pseudoprime}
-TODO: split \texttt{pseudoprime.R} into \texttt{fermat.R} and
-\texttt{pseudoprime.R}; talk about \texttt{@param}, \texttt{@return},
-\texttt{@callGraphPrimitives} in the context of \texttt{fermat.R},
-and \texttt{@include} and \texttt{@export} in the context of
+Talk about \texttt{@include} and \texttt{@export} in the context of
\texttt{pseudoprime.R}.
+\subsection{Running \Roxygen{}}
+
+Talk about \texttt{R CMD roxygen} vs. \texttt{roxygenize}.
+
<<>>=
roxygenize('pseudoprime',
roxygen.dir='pseudoprime',
@@ -123,10 +149,4 @@
@
-\begin{figure}[ht]
- \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