Merged documentation for addPackage() and updatePackages() into singl…

…e topic #40. Also reduced example runtime #43.

R/updatePackages.R

@@ -1,18 +1,19 @@
-#' Compare miniCRAN Packages with CRAN-like Repositories
+#' Check for available package updates in a miniCRAN repo.
 #'
-#' \code{oldPackages} indicates packages which have a (suitable) later version on the repositories whereas \code{\link{updatePackages}} offers to download and install such packages.
-#'
-#' These functions are based on \code{\link{update.packages}} and related, except rather than looking for locally installed packages they look for the package sources and binaries being hosted in the miniCRAN repository.
+#' \code{oldPackages} indicates packages which have a (suitable) later version on the repositories whereas \code{updatePackages} offers to download and install such packages.
 #'
+#' These functions are based on \code{\link{update.packages}}.  However, rather than looking for locally installed packages they look for the package source and binaries in the miniCRAN repository.
 #'
+#' @name updatePackages
+#' 
 #' @inheritParams makeRepo
 #' @inheritParams pkgDep
 #'
 #' @param method  Download method, see \code{\link{download.file}}.
 #'
 #' @param availableLocal all packages hosted in the miniCRAN repo, as returned by \code{\link{pkgAvail}}. A subset can be specified; currently this must be in the same (character matrix) format as returned by \code{\link{pkgAvail}}.
 #'
-#' @return A matrix with one row per package, row names the package names and column names "Package", "LocalVer", "ReposVer", and "Repository".
+#' @return \code{oldPackages} returns a matrix with one row per package and columns for "Package", "LocalVer", "ReposVer" and "Repository".  The matrix row names the package names.
 #'
 #' @seealso \code{\link{updatePackages}}, \code{\link{pkgAvail}}.
 #'
@@ -50,28 +51,18 @@ oldPackages <- function (path=NULL, repos=getOption("repos"),
 }
 
 
-#  ------------------------------------------------------------------------
 
 
-#' Compare miniCRAN Packages with CRAN-like Repositories
-#'
-#' \code{\link{oldPackages}} indicates packages which have a (suitable) later version on the repositories whereas \code{updatePackages} offers to download and install such packages.
-#'
-#' These functions are based on \code{\link{update.packages}} and related, except rather than looking for locally installed packages they look for the package sources and binaries being hosted in the miniCRAN repository.
-#'
 #' @inheritParams oldPackages
 #' @inheritParams makeRepo
 #'
-#' @param oldPkgs if specified as non-NULL, updatePackages() only considers these packages for updating. This may be a character vector of package names or a matrix as returned by oldPackages().
+#' @param oldPkgs if specified as non-NULL, \code{updatePackages()} only considers these packages for updating. This may be a character vector of package names or a matrix as returned by \code{oldPackages()}.
 #'
 #' @param ask logical indicating whether to ask user before packages are actually downloaded and installed, or the character string "\code{graphics}", which brings up a widget to allow the user to (de-)select from the list of packages which could be updated or added. The latter value only works on systems with a GUI version of \code{\link{select.list}}, and is otherwise equivalent to \code{ask = TRUE}.
 #'
-#' @return \code{NULL} invisibly.
+#' @return \code{updatePackages} returns \code{NULL} invisibly.
 #'
 #' @export
-#' @family update repo functions
-#' 
-#' @example /inst/examples/example_updatePackages.R
 #'
 updatePackages <- function (path=NULL, repos=getOption("repos"),
                             method, ask=TRUE, availPkgs=pkgAvail(repos=repos, type=type),

man/addOldPackage.Rd

@@ -92,7 +92,8 @@ pkgList
 \seealso{
 Other update repo functions: \code{\link{addPackage}};
   \code{\link{checkVersions}}; \code{\link{makeRepo}},
-  \code{\link{updateRepoIndex}}; \code{\link{oldPackages}};
+  \code{\link{updateRepoIndex}}; \code{\link{oldPackages}},
+  \code{\link{updatePackages}},
   \code{\link{updatePackages}}
 }
 

man/addPackage.Rd

@@ -87,7 +87,8 @@ pkgList
 \seealso{
 Other update repo functions: \code{\link{addOldPackage}};
   \code{\link{checkVersions}}; \code{\link{makeRepo}},
-  \code{\link{updateRepoIndex}}; \code{\link{oldPackages}};
+  \code{\link{updateRepoIndex}}; \code{\link{oldPackages}},
+  \code{\link{updatePackages}},
   \code{\link{updatePackages}}
 }
 

man/checkVersions.Rd

@@ -78,7 +78,8 @@ pkgList
 \seealso{
 Other update repo functions: \code{\link{addOldPackage}};
   \code{\link{addPackage}}; \code{\link{makeRepo}},
-  \code{\link{updateRepoIndex}}; \code{\link{oldPackages}};
+  \code{\link{updateRepoIndex}}; \code{\link{oldPackages}},
+  \code{\link{updatePackages}},
   \code{\link{updatePackages}}
 }
 

man/makeRepo.Rd

@@ -108,6 +108,7 @@ unlink(pth, recursive = TRUE)
 \seealso{
 Other update repo functions: \code{\link{addOldPackage}};
   \code{\link{addPackage}}; \code{\link{checkVersions}};
-  \code{\link{oldPackages}}; \code{\link{updatePackages}}
+  \code{\link{oldPackages}}, \code{\link{updatePackages}},
+  \code{\link{updatePackages}}
 }
 

man/repoBinPath.Rd

@@ -8,7 +8,7 @@ repoBinPath(path, type, Rversion)
 \arguments{
 \item{path}{Destination download path. This path is the root folder of your new repository.}
 
-\item{type}{Possible values are (currently) "source", "mac.binary" and "win.binary": the binary types can be listed and downloaded but not installed on other platforms.  Passed to \code{\link{download.packages}}.}
+\item{type}{character, indicating the type of package to download and install. See \code{\link{install.packages}}.}
 
 \item{Rversion}{List with two named elements: `major` and `minor`. If not supplied, defaults to system version of R, using \code{\link{R.version}}.  Only used if \code{type} is not "source"}
 }

man/updatePackages.Rd

@@ -1,8 +1,14 @@
 % Generated by roxygen2 (4.0.2): do not edit by hand
 \name{updatePackages}
+\alias{oldPackages}
 \alias{updatePackages}
-\title{Compare miniCRAN Packages with CRAN-like Repositories}
+\title{Check for available package updates in a miniCRAN repo.}
 \usage{
+oldPackages(path = NULL, repos = getOption("repos"),
+  availPkgs = pkgAvail(repos = repos, type = type), method,
+  availableLocal = pkgAvail(repos = path, type = type), type = "source",
+  Rversion = R.version)
+
 updatePackages(path = NULL, repos = getOption("repos"), method,
   ask = TRUE, availPkgs = pkgAvail(repos = repos, type = type),
   oldPkgs = NULL, type = "source", Rversion = getRversion(),
@@ -13,28 +19,32 @@ updatePackages(path = NULL, repos = getOption("repos"), method,
 
 \item{repos}{URL(s) of the 'contrib' sections of the repositories, e.g. \code{"http://cran.us.r-project.org"}. Passed to \code{\link{available.packages}}}
 
-\item{method}{Download method, see \code{\link{download.file}}.}
-
-\item{ask}{logical indicating whether to ask user before packages are actually downloaded and installed, or the character string "\code{graphics}", which brings up a widget to allow the user to (de-)select from the list of packages which could be updated or added. The latter value only works on systems with a GUI version of \code{\link{select.list}}, and is otherwise equivalent to \code{ask = TRUE}.}
-
 \item{availPkgs}{Vector of available packages.  Defaults to reading this list from CRAN, using \code{\link{available.packages}}}
 
-\item{oldPkgs}{if specified as non-NULL, updatePackages() only considers these packages for updating. This may be a character vector of package names or a matrix as returned by oldPackages().}
+\item{method}{Download method, see \code{\link{download.file}}.}
+
+\item{availableLocal}{all packages hosted in the miniCRAN repo, as returned by \code{\link{pkgAvail}}. A subset can be specified; currently this must be in the same (character matrix) format as returned by \code{\link{pkgAvail}}.}
 
 \item{type}{Possible values are (currently) "source", "mac.binary" and "win.binary": the binary types can be listed and downloaded but not installed on other platforms.  Passed to \code{\link{download.packages}}.}
 
 \item{Rversion}{List with two named elements: `major` and `minor`. If not supplied, defaults to system version of R, using \code{\link{R.version}}.  Only used if \code{type} is not "source"}
 
+\item{ask}{logical indicating whether to ask user before packages are actually downloaded and installed, or the character string "\code{graphics}", which brings up a widget to allow the user to (de-)select from the list of packages which could be updated or added. The latter value only works on systems with a GUI version of \code{\link{select.list}}, and is otherwise equivalent to \code{ask = TRUE}.}
+
+\item{oldPkgs}{if specified as non-NULL, \code{updatePackages()} only considers these packages for updating. This may be a character vector of package names or a matrix as returned by \code{oldPackages()}.}
+
 \item{quiet}{If TRUE, suppress status messages (if any), and the progress bar during download.}
 }
 \value{
-\code{NULL} invisibly.
+\code{oldPackages} returns a matrix with one row per package and columns for "Package", "LocalVer", "ReposVer" and "Repository".  The matrix row names the package names.
+
+\code{updatePackages} returns \code{NULL} invisibly.
 }
 \description{
-\code{\link{oldPackages}} indicates packages which have a (suitable) later version on the repositories whereas \code{updatePackages} offers to download and install such packages.
+\code{oldPackages} indicates packages which have a (suitable) later version on the repositories whereas \code{updatePackages} offers to download and install such packages.
 }
 \details{
-These functions are based on \code{\link{update.packages}} and related, except rather than looking for locally installed packages they look for the package sources and binaries being hosted in the miniCRAN repository.
+These functions are based on \code{\link{update.packages}}.  However, rather than looking for locally installed packages they look for the package source and binaries in the miniCRAN repository.
 }
 \examples{
 ### `oldPackages` and `updatePackages` require an existing miniCRAN repo
@@ -80,9 +90,10 @@ pkgList
 }
 }
 \seealso{
+\code{\link{updatePackages}}, \code{\link{pkgAvail}}.
+
 Other update repo functions: \code{\link{addOldPackage}};
   \code{\link{addPackage}}; \code{\link{checkVersions}};
-  \code{\link{makeRepo}}, \code{\link{updateRepoIndex}};
-  \code{\link{oldPackages}}
+  \code{\link{makeRepo}}, \code{\link{updateRepoIndex}}
 }