more detailed docs

R/versions.R

@@ -61,7 +61,9 @@ atime_versions_install <- function(Package, pkg.path, new.Package.vec, sha.vec,
  "not installing %s because it already exists in %s",
  new.Package, first.lib))
  }
- }else if(sha != ""){#new.Package not in lib
+ }else if(sha == ""){
+ install.packages(Package)
+ }else{
  sha.path <- paste0(new.path,".",sha)
  file.rename(new.path, sha.path)
  repo <- git2r::repository(sha.path)

man/atime_pkg.Rd

@@ -6,16 +6,22 @@
  versions (base, HEAD, CRAN, merge-base).}
 \usage{atime_pkg(pkg.path)}
 \arguments{
- \item{pkg.path}{path to package source directory.}
+ \item{pkg.path}{path to git repository containing R package.}
 }
-\details{There should be a file named pkg.path/inst/atime/tests.R which
+\details{
+ There should be a file named pkg.path/inst/atime/tests.R which
  defines \code{test.list}, a list with names corresponding to different
  tests. Each
  element should be a list with at least three named elements: \code{N},
  \code{setup}, \code{expr}, (possibly others such as
  \code{pkg.edit.fun} and \code{version_name="1234567890abcdef"})
- to be passed as named
- arguments to \code{atime_versions}.}
+ to be passed as named arguments to \code{atime_versions}, along with
+ the following versions which are passed using the \code{sha.vec} argument:
+ base ref comes from GITHUB_BASE_REF environment variable (default master),
+ HEAD ref is the branch that you want to merge into base,
+ CRAN is current published version (sha value \code{""}),
+ merge-base is most recent common ancestor commit between base and HEAD.
+}
 \value{Named list, names come from names of \code{test.list}, and values
  come from results of \code{atime_versions}. Side effect is that
  data/plot files are saved to the inst/atime directory.}

man/atime_versions.Rd

@@ -18,17 +18,18 @@ atime_versions(
  In contrast to \code{expr},
  no replacement of \code{Package:} is performed.
  }
- \item{expr}{code with package double-colon prefix, for example
- \code{Package::fun(argA, argB)}, where Package is the name of the
+ \item{expr}{
+ code with package double-colon prefix, for example
+ \code{PKG::fun(argA, argB)}, where PKG is the name of the
  package specified by \code{pkg.path}. This code will be
  evaluated for each different package version, by replacing
- \code{Package:} by \code{Package.SHA:}.
+ \code{PKG:} by \code{PKG.SHA:}.
  To run different versions of implicitly-called functions
  like \code{DT[i,j]}, you need
  to call them explicitly, as in 
  \code{data.table:::`[.data.table`(DT,i,j)}.
  }
- \item{sha.vec}{named character vector / list of SHA commit IDs.}
+ \item{sha.vec}{named character vector / list of versions.}
  \item{times}{number of times to evaluate each timed expression.}
  \item{seconds.limit}{if the median timing of any expression exceeds
  this many seconds, then no timings for larger N are computed.}
@@ -37,22 +38,23 @@ atime_versions(
  installation, should typically replace instances of PKG with
  PKG.SHA, default works with Rcpp packages.}
  \item{results}{logical, save results?}
- \item{\dots}{named SHA/commit IDs to time. Values passed as branch
- arg to \code{git2r::checkout}, names used to identify/interpret
- this version
- of the code in the output.}
+ \item{\dots}{named versions.}
+}
+\details{
+ For convenience, versions can
+ be specified either as code (\dots), data (\code{sha.vec}), or both.
+ Each version should be either \code{""} (to use currently installed
+ version of package, or if missing, install most recent
+ version from CRAN) or a SHA1 hash, which is passed as branch
+ arg to \code{git2r::checkout}; version names used to identify/interpret
+ the output/plots.
 }
-\details{First each version specified by \dots is checked out and
- installed (to whatever R library is first on \code{.libPaths()}),
- using the package name Package.SHA. Then the atime function is called
- with arguments defined by the different SHA arguments,
- \code{atime(name1=Package.SHA1::fun(argA, argB),
- name2=Package.SHA2::fun(argA,argB))}.}
 \value{list of class atime with elements \code{seconds.limit} (numeric
  input param), \code{timings} (data table of results).}
 \seealso{
- \code{\link{atime_versions_exprs}} which is used to create the
- different packages and expressions.
+ \code{\link{atime_versions_exprs}} 
+ converts \code{expr} into a list of expressions, one for each version,
+ passed to \code{\link{atime}} as the \code{expr.list} argument.
 }
 
 \author{Toby Dylan Hocking}

man/atime_versions_exprs.Rd

@@ -12,27 +12,44 @@ verbose=FALSE,
 pkg.edit.fun=pkg.edit.default, ...)}
 \arguments{
  \item{pkg.path}{Path to git repo containing R package.}
- \item{expr}{code with package double-colon prefix, for example
- Package::fun(argA, argB) which will be
- evaluated for each different package version.}
- \item{sha.vec}{named character vector / list of SHA commit IDs.}
+ \item{expr}{
+ code with package double-colon prefix, for example
+ \code{PKG::fun(argA, argB)}, where PKG is the name of the
+ package specified by \code{pkg.path}. This code will be
+ evaluated for each different package version, by replacing
+ \code{PKG:} by \code{PKG.SHA:}.
+ To run different versions of implicitly-called functions
+ like \code{DT[i,j]}, you need
+ to call them explicitly, as in 
+ \code{data.table:::`[.data.table`(DT,i,j)}.
+ }
+ \item{sha.vec}{named character vector / list of versions.}
  \item{verbose}{logical, print messages after every data size?}
  \item{pkg.edit.fun}{function called to edit package before
- installation, should typically replace instances of PKG with
- PKG.SHA, default works with Rcpp packages.}
- \item{\dots}{named SHA/commit IDs to time. Values passed as branch
- arg to \code{git2r::checkout}, names used to identify/interpret
- this version
- of the code in the output.}
+ installation, should typically replace instances of \code{PKG} with
+ \code{PKG.SHA}, default works with Rcpp packages, but does not work
+ with all packages. For an example of a custom package editing
+ function, see the atime vignette about data.table.}
+ \item{\dots}{named versions.}
+}
+\details{
+ For convenience, versions can
+ be specified either as code (\dots), data (\code{sha.vec}), or both.
+ Each version should be either \code{""} (to install most recent
+ version from CRAN) or a SHA1 hash, which is passed as branch
+ arg to \code{git2r::checkout}; version names used to identify/interpret
+ the output/plots.
+ Each version is installed as a separate package
+ (to whatever R library is first on \code{.libPaths()}),
+ using the package name \code{PKG.SHA}.
 }
-\details{First each version is checked out and
- installed (to whatever R library is first on \code{.libPaths()}),
- using the package name Package.SHA. Then an expression is created for
- each version, by replacing the PKG name in colon-prefix with PKG.SHA, 
+\value{
+ A list of expressions, one for
+ each version, created by replacing \code{PKG:}
+ in \code{expr} with \code{PKG.SHA:}, 
  \code{atime(name1=Package.SHA1::fun(argA, argB),
- name2=Package.SHA2::fun(argA,argB))}. For convenience, versions can
- be specified either as code (\dots) or data (\code{sha.vec}).}
-\value{list of expressions.}
+ name2=Package.SHA2::fun(argA,argB))}.
+}
 
 \author{Toby Dylan Hocking}