From 129215f3977683ab4295c9e8a01ae1820e3ad641 Mon Sep 17 00:00:00 2001
From: mpadge <mark.padgham@email.com>
Date: Fri, 23 Jun 2023 14:23:27 +0200
Subject: [PATCH] add and document 'trace_lists' param for #19

But not yet functional
---
 R/trace-package.R    | 13 +++++++++----
 man/trace_package.Rd | 14 ++++++++++----
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/R/trace-package.R b/R/trace-package.R
index 0b996c2..eddf92d 100644
--- a/R/trace-package.R
+++ b/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
diff --git a/man/trace_package.Rd b/man/trace_package.Rd
index 9235c9c..ef2ed8e 100644
--- a/man/trace_package.Rd
+++ b/man/trace_package.Rd
@@ -6,14 +6,19 @@
 \usage{
 trace_package(
   package = NULL,
+  pkg_dir = NULL,
   functions = NULL,
   types = c("examples", "tests"),
-  pkg_dir = NULL
+  trace_lists = FALSE
 )
 }
 \arguments{
 \item{package}{Name of package to be traced (as character value).}
 
+\item{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.)}
+
 \item{functions}{Optional character vector of names of functions to trace.
 Defaults to tracing all functions.}
 
@@ -21,9 +26,10 @@ Defaults to tracing all functions.}
 values of "examples" or "tests" (as for \code{tools::testInstalledPackage}). Note
 that only tests run via the \pkg{testthat} package can be traced.}
 
-\item{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.)}
+\item{trace_lists}{If \code{TRUE}, trace into any nested list parameters
+(including \code{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 '\if{html}{\out{<par>}}$\if{html}{\out{<item>}}', for example 'Orange$age'.}
 }
 \value{
 A \code{data.frame} of data on every parameter of every function as