add and document 'trace_lists' param for #19

But not yet functional

R/trace-package.R

@@ -2,14 +2,18 @@
 #' Trace all parameters for all functions in a specified package
 #'
 #' @param package Name of package to be traced (as character value).
+#' @param pkg_dir For "types" including "tests", a local directory to the source
+#' code of the package. (This is needed because installed versions do not
+#' generally include tests.)
 #' @param functions Optional character vector of names of functions to trace.
 #' Defaults to tracing all functions.
 #' @param types The types of code to be run to generate traces: one or both
 #' values of "examples" or "tests" (as for `tools::testInstalledPackage`). Note
 #' that only tests run via the \pkg{testthat} package can be traced.
-#' @param pkg_dir For "types" including "tests", a local directory to the source
-#' code of the package. (This is needed because installed versions do not
-#' generally include tests.)
+#' @param trace_lists If `TRUE`, trace into any nested list parameters
+#' (including `data.frame`-type objects), and return type information on each
+#' list component. The parameter names for these list-components are then
+#' specified in "dollar-notation", as '<par>$<item>', for example 'Orange$age'.
 #' @return A `data.frame` of data on every parameter of every function as
 #' specified in code provided in package examples.
 #' @export
@@ -19,9 +23,10 @@
 #' res <- trace_package (pkg_dir = "/<path>/<to>/<local>/<pacakge>")
 #' }
 trace_package <- function (package = NULL,
+                           pkg_dir = NULL,
                            functions = NULL,
                            types = c ("examples", "tests"),
-                           pkg_dir = NULL) {
+                           trace_lists = FALSE) {
 
     types <- match.arg (types, c ("examples", "tests"),
         several.ok = TRUE