From a0d8b6d25a1db33fff7bab297e2755a57e25be4b Mon Sep 17 00:00:00 2001
From: Toby Dylan Hocking <Toby.Hocking@nau.edu>
Date: Tue, 7 Nov 2023 20:45:32 +0000
Subject: [PATCH] clarify no replacement in setup

---
 man/atime_versions.Rd | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/man/atime_versions.Rd b/man/atime_versions.Rd
index f15868a..2af59d9 100644
--- a/man/atime_versions.Rd
+++ b/man/atime_versions.Rd
@@ -3,18 +3,31 @@
 \title{Asymptotic timing of git versions}
 \description{Computation time and memory for a single R expression
   evaluated using several different git versions.}
-\usage{atime_versions(
-pkg.path, N, setup, expr, sha.vec=NULL,
-times=10, seconds.limit=0.01, verbose=FALSE,
-pkg.edit.fun=pkg.edit.default, results=TRUE,
-...)}
+\usage{
+atime_versions(
+ pkg.path, N, setup, expr, sha.vec=NULL,
+ times=10, seconds.limit=0.01, verbose=FALSE,
+ pkg.edit.fun=pkg.edit.default, results=TRUE,
+ ...)
+}
 \arguments{
   \item{pkg.path}{Path to git repo containing R package.}
   \item{N}{numeric vector of data sizes to vary.}
-  \item{setup}{expression to evaluate for every data size, before timings.}
+  \item{setup}{
+    expression to evaluate for every data size, before timings.
+    In contrast to \code{expr},
+    no replacement of \code{Package:} is performed.
+  }
   \item{expr}{code with package double-colon prefix, for example
-    Package::fun(argA, argB) which will be
-    evaluated for each different package version.}
+    \code{Package::fun(argA, argB)}, where Package 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:}.
+    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{times}{number of times to evaluate each timed expression.}
   \item{seconds.limit}{if the median timing of any expression exceeds
@@ -37,6 +50,10 @@ pkg.edit.fun=pkg.edit.default, results=TRUE,
     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.
+}
 
 \author{Toby Dylan Hocking}