Update documentation

R/draft_validation.R

@@ -51,7 +51,7 @@
 #'   agent report generated by printing the *agent* or calling
 #'   [get_agent_report()].
 #'   
-#' @param file_name *File name*
+#' @param filename *File name*
 #' 
 #'   `scalar<character>` // *default:* `tbl_name`
 #' 
@@ -325,7 +325,7 @@
 draft_validation <- function(
     tbl,
     tbl_name = NULL,
-    file_name = tbl_name,
+    filename = tbl_name,
     path = NULL,
     lang = NULL,
     output_type = c("R", "Rmd"),
@@ -389,15 +389,15 @@ draft_validation <- function(
     read_fn_name <- NULL
   }
 
-  if (file_name == ".") {
-    file_name <- NULL
+  if (filename == ".") {
+    filename <- NULL
   }
 
   # Create the filename for the pointblank file
   file_name <- 
     resolve_file_filename(
       agent = agent,
-      name = file_name,
+      name = filename,
       output_type = output_type
     )
 

R/tbl_match.R

@@ -34,10 +34,14 @@
 #' 
 #' @inheritParams col_vals_gt
 #' 
-#' @param tbl_compare A table to compare against the target table. This can
-#'   either be a table object, a table-prep formula. This can be a table object
-#'   such as a data frame, a tibble, a `tbl_dbi` object, or a `tbl_spark`
-#'   object. Alternatively, a table-prep formula (`~ <table reading code>`) or a
+#' @param tbl_compare *A data table for comparison*
+#' 
+#'   `obj:<tbl_*>` // **required**
+#' 
+#'   A table to compare against the target table. This can either be a table
+#'   object, a table-prep formula. This can be a table object such as a data
+#'   frame, a tibble, a `tbl_dbi` object, or a `tbl_spark` object.
+#'   Alternatively, a table-prep formula (`~ <table reading code>`) or a
 #'   function (`function() <table reading code>`) can be used to lazily read in
 #'   the table at interrogation time.
 #'   

R/validate_rmd.R

@@ -38,15 +38,21 @@ test_options <- new.env(parent = emptyenv())
 #' failures. Clicking the button reveals the otherwise hidden validation
 #' statements and their error messages (if any).
 #'
-#' @param summary If `TRUE` (the default), then there will be a leading summary
-#'   of all validations in the rendered R Markdown document. With `FALSE`, this
-#'   element is not shown.
+#' @param summary *Include a validation summary*
+#' 
+#'   `scalar<logical>` // *default:* `TRUE`
+#' 
+#'   If `TRUE` then there will be a leading summary of all validations in the
+#'   rendered R Markdown document. With `FALSE`, this element is not shown.
 #'   
-#' @param log_to_file An option to log errors to a text file. By default, no
-#'   logging is done but `TRUE` will write log entries to
-#'   `"validation_errors.log"` in the working directory. To both enable logging
-#'   and to specify a file name, include a path to a log file of the desired
-#'   name.
+#' @param log_to_file *Log validation results to a file*
+#' 
+#'   `scalar<logical|character>` // *default:* `NULL` (`optional`)
+#' 
+#'   An option to log errors to a text file. By default, no logging is done but
+#'   `TRUE` will write log entries to `"validation_errors.log"` in the working
+#'   directory. To both enable logging and to specify a file name, include a
+#'   path to a log file of the desired name.
 #'
 #' @family Planning and Prep
 #' @section Function ID:

R/write_testthat_file.R

@@ -121,32 +121,50 @@
 #'   A **pointblank** *agent* object that is commonly created through the use of
 #'   the [create_agent()] function.
 #' 
-#' @param name An optional name for for the **testhat** test file. This should
-#'   be a name without extension and without the leading `"test-"` text. If
-#'   nothing is supplied, the name will be derived from the `tbl_name` in the
-#'   agent. If that's not present, a generic name will be used.
+#' @param name *Name for generated testthat file*
+#' 
+#'   `scalar<character>` // *default:* `NULL` (`optional`)
+#' 
+#'   An optional name for for the **testhat** test file. This should be a name
+#'   without extension and without the leading `"test-"` text. If nothing is
+#'   supplied, the name will be derived from the `tbl_name` in the agent. If
+#'   that's not present, a generic name will be used.
+#'   
+#' @param path *File path*
+#' 
+#'   `scalar<character>` // *default:* `NULL` (`optional`)
+#' 
+#'   A path can be specified here if there shouldn't be an attempt to place the
+#'   file in `testthat/tests`.
 #'   
-#' @param path A path can be specified here if there shouldn't be an attempt to
-#'   place the file in `testthat/tests`.
+#' @param overwrite *Overwrite a previous file of the same name*
+#' 
+#'   `scalar<logical>` // *default:* `FALSE`
 #'   
-#' @param overwrite Should a **testthat** file of the same name be overwritten?
-#'   By default, this is `FALSE`.
+#'   Should a **testthat** file of the same name be overwritten?
 #'   
-#' @param skips This is an optional vector of test-skipping keywords modeled
-#'   after the **testthat** `skip_on_*()` functions. The following keywords can
-#'   be used to include `skip_on_*()` statements: `"cran"`
-#'   ([testthat::skip_on_cran()]), `"travis"` ([testthat::skip_on_travis()]),
-#'   `"appveyor"` ([testthat::skip_on_appveyor()]), `"ci"`
-#'   ([testthat::skip_on_ci()]), `"covr"` ([testthat::skip_on_covr()]), `"bioc"`
+#' @param skips *Test skipping*
+#' 
+#'   `vector<character>` // *default:* `NULL` (`optional`)
+#' 
+#'   This is an optional vector of test-skipping keywords modeled after the
+#'   **testthat** `skip_on_*()` functions. The following keywords can be used to
+#'   include `skip_on_*()` statements: `"cran"` ([testthat::skip_on_cran()]),
+#'   `"travis"` ([testthat::skip_on_travis()]), `"appveyor"`
+#'   ([testthat::skip_on_appveyor()]), `"ci"` ([testthat::skip_on_ci()]),
+#'   `"covr"` ([testthat::skip_on_covr()]), `"bioc"`
 #'   ([testthat::skip_on_bioc()]). There are keywords for skipping tests on
 #'   certain operating systems and all of them will insert a specific
 #'   [testthat::skip_on_os()] call. These are `"windows"`
 #'   (`skip_on_os("windows")`), `"mac"` (`skip_on_os("mac")`), `"linux"`
 #'   (`skip_on_os("linux")`), and `"solaris"` (`skip_on_os("solaris")`). These
 #'   calls will be placed at the top of the generated **testthat** test file.
 #'   
-#' @param quiet Should the function *not* inform when the file is written? By
-#'   default this is `FALSE`.
+#' @param quiet *Inform (or not) upon file writing*
+#' 
+#'   `scalar<logical>` // *default:* `FALSE`
+#' 
+#'   Should the function *not* inform when the file is written?
 #'   
 #' @return Invisibly returns `TRUE` if the **testthat** file has been written. 
 #' 

R/yaml_read_agent.R

@@ -36,10 +36,17 @@
 #' [yaml_agent_show_exprs()] function. That function shows us (in the console)
 #' the **pointblank** expressions for generating the described validation plan.
 #'   
-#' @param filename The name of the YAML file that contains fields related to an
-#'   *agent*.
+#' @param filename *File name*
+#' 
+#'   `scalar<character>` // **required**
+#' 
+#'   The name of the YAML file that contains fields related to an *agent*.
 #'   
-#' @param path An optional path to the YAML file (combined with `filename`).
+#' @param path *File path*
+#' 
+#'   `scalar<character>` // *default:* `NULL` (`optional`)
+#' 
+#'   An optional path to the YAML file (combined with `filename`).
 #'   
 #' @return A `ptblank_agent` object.
 #'   
@@ -156,10 +163,17 @@ yaml_read_agent <- function(
 #' that function. As with [yaml_read_agent()] the agent is returned except, this
 #' time, it has intel from the interrogation.
 #' 
-#' @param filename The name of the YAML file that contains fields related to an
-#'   *agent*.
+#' @param filename *File name*
+#' 
+#'   `scalar<character>` // **required**
+#' 
+#'   The name of the YAML file that contains fields related to an *agent*.
 #'   
-#' @param path An optional path to the YAML file (combined with `filename`).
+#' @param path #' @param path *File path*
+#' 
+#'   `scalar<character>` // *default:* `NULL` (`optional`)
+#'    
+#'   An optional path to the YAML file (combined with `filename`).
 #' 
 #' @return A `ptblank_agent` object.
 #'
@@ -258,10 +272,17 @@ yaml_agent_interrogate <- function(
 #' [yaml_write()] function with a pre-existing *agent*, or, it can be carefully
 #' written by hand.
 #'
-#' @param filename The name of the YAML file that contains fields related to an
-#'   *agent*.
+#' @param filename *File name*
+#' 
+#'   `scalar<character>` // **required**
+#' 
+#'   The name of the YAML file that contains fields related to an *agent*.
 #'   
-#' @param path An optional path to the YAML file (combined with `filename`).
+#' @param path #' @param path *File path*
+#' 
+#'   `scalar<character>` // *default:* `NULL` (`optional`)
+#'    
+#'   An optional path to the YAML file (combined with `filename`).
 #' 
 #' @section Examples:
 #' 

R/yaml_read_informant.R

@@ -27,10 +27,17 @@
 #' intact. The *informant* object can be given more information through use of
 #' the `info_*()` functions.
 #'   
-#' @param filename The name of the YAML file that contains fields related to an
-#'   *informant*.
+#' @param filename *File name*
+#' 
+#'   `scalar<character>` // **required**
+#' 
+#'   The name of the YAML file that contains fields related to an *informant*.
 #'   
-#' @param path An optional path to the YAML file (combined with `filename`).
+#' @param path *File path*
+#' 
+#'   `scalar<character>` // *default:* `NULL` (`optional`)
+#' 
+#'   An optional path to the YAML file (combined with `filename`).
 #' 
 #' @return A `ptblank_informant` object.
 #' 
@@ -126,10 +133,17 @@ yaml_read_informant <- function(
 #' informant is returned except, this time, it has been updated with the latest
 #' information from the target table.
 #'
-#' @param filename The name of the YAML file that contains fields related to an
-#'   *informant*.
+#' @param filename *File name*
+#' 
+#'   `scalar<character>` // **required**
+#' 
+#'   The name of the YAML file that contains fields related to an *informant*.
 #'   
-#' @param path An optional path to the YAML file (combined with `filename`).
+#' @param path *File path*
+#' 
+#'   `scalar<character>` // *default:* `NULL` (`optional`)
+#' 
+#'   An optional path to the YAML file (combined with `filename`).
 #' 
 #' @return A `ptblank_informant` object.
 #'
@@ -197,8 +211,7 @@ yaml_informant_incorporate <- function(
   informant
 }
 
-expr_from_informant_yaml <- function(path,
-                                     incorporate = FALSE) {
+expr_from_informant_yaml <- function(path, incorporate = FALSE) {
 
   # Read the YAML file with `yaml::read_yaml()`
   y <- yaml::read_yaml(file = path)

R/yaml_write.R

@@ -39,32 +39,55 @@
 #' This option can be set when using [create_agent()]/[create_informant()] or
 #' with [set_tbl()] (useful with an existing agent or informant object).
 #' 
-#' @param ... Any mix of **pointblank** objects such as the *agent*
+#' @param ... *Pointblank agents, informants, table stores*
+#' 
+#'   `<series of obj:<ptblank_agent|ptblank_informant|tbl_store>>`
+#'   // **required**
+#' 
+#'   Any mix of **pointblank** objects such as the *agent*
 #'   (`ptblank_agent`), the *informant* (`ptblank_informant`), or the table
 #'   store (`tbl_store`). The agent and informant can be combined into a single
 #'   YAML file (so long as both objects refer to the same table). A table store
 #'   cannot be combined with either an agent or an informant so it must undergo
 #'   conversion alone.
 #'   
-#' @param .list Allows for the use of a list as an input alternative to `...`.
+#' @param .list *Alternative to `...`*
 #' 
-#' @param filename The name of the YAML file to create on disk. It is
-#'   recommended that either the `.yaml` or `.yml` extension be used for this
-#'   file. If not provided then default names will be used (`"tbl_store.yml"`)
-#'   for a table store and the other objects will get default naming to the
-#'   effect of `"<object>-<tbl_name>.yml"`.
+#'   `<list of multiple expressions>` // **required** (or, use `...`)
 #' 
-#' @param path An optional path to which the YAML file should be saved (combined
-#'   with `filename`).
+#'   Allows for the use of a list as an input alternative to `...`.
 #' 
-#' @param expanded Should the written validation expressions for an *agent* be
-#'   expanded such that **tidyselect** and [vars()] expressions for columns are
-#'   evaluated, yielding a validation function per column? By default, this is
-#'   `FALSE` so expressions as written will be retained in the YAML
-#'   representation.
+#' @param filename *File name*
+#' 
+#'   `scalar<character>` // *default:* `NULL` (`optional`)
+#' 
+#'   The name of the YAML file to create on disk. It is recommended that either
+#'   the `.yaml` or `.yml` extension be used for this file. If not provided then
+#'   default names will be used (`"tbl_store.yml"`) for a table store and the
+#'   other objects will get default naming to the effect of
+#'   `"<object>-<tbl_name>.yml"`.
+#' 
+#' @param path *File path*
+#' 
+#'   `scalar<character>` // *default:* `NULL` (`optional`)
+#' 
+#'   An optional path to which the YAML file should be saved (combined with
+#'   `filename`).
+#' 
+#' @param expanded *Expand validation when repeating across multiple columns*
+#' 
+#'   `scalar<logical>` // *default:* `FALSE`
+#' 
+#'   Should the written validation expressions for an *agent* be expanded such
+#'   that **tidyselect** and [vars()] expressions for columns are evaluated,
+#'   yielding a validation function per column? By default, this is `FALSE` so
+#'   expressions as written will be retained in the YAML representation.
+#' 
+#' @param quiet *Inform (or not) upon file writing*
+#' 
+#'   `scalar<logical>` // *default:* `FALSE`
 #' 
-#' @param quiet Should the function *not* inform when the file is written? By
-#'   default this is `FALSE`.
+#'.  Should the function *not* inform when the file is written?
 #'   
 #' @return Invisibly returns `TRUE` if the YAML file has been written.
 #'