Clean up the prose added for v1.0

NEWS.md

@@ -78,7 +78,7 @@ spelled as make variables: `list(stan_threads = TRUE)` comes back as
 * Every `cpp_options` entry must now be named, with a make variable name. An
 unnamed entry gets an error saying where it belongs: `list(NAME = value)` for a
 plain assignment, `cmdstan_make_local()` for `+=` and the other makefile
-operators. Previously unnamed entries reached `make` but nothing else saw them.
+operators. Previously unnamed entries reached make but nothing else saw them.
 (#1250)
 * `cpp_options = list(stan_threads = FALSE)` now turns threading off, even when
 `make/local` turns it on, and the same holds for `FALSE` on any option.
@@ -107,14 +107,14 @@ error that points at the right argument. (#1258)
 `STANCFLAGS`. (#1258)
 * Named `stanc_options` values such as `list(canonicalize = "deprecations")` and
 numeric ones such as `list("max-line-length" = 78)` now work. Previously the
-named values reached `stanc` shell-quoted, which it rejected, and the numeric
+named values reached stanc shell-quoted, which it rejected, and the numeric
 ones were dropped. (#1227, #1233)
-* A `stanc` error now stops the build immediately and shows `stanc`'s message.
+* A stanc error now stops the build immediately and shows stanc's message.
 Previously it surfaced several steps later. (#1227)
 * An include path that does not exist is now reported by its absolute path.
 (#1227)
 * `$include_paths()` now returns absolute paths, resolved when the model is
-created. Previously a relative include path was resolved on every `stanc` call,
+created. Previously a relative include path was resolved on every stanc call,
 so changing the working directory could point `#include` at the wrong directory.
 (#1229)
 * `#include` directories with spaces in their paths now work. (#820, #1230)
@@ -229,7 +229,7 @@ not created and keeps saved metric files after the fitted model is
 garbage-collected. (#1021)
 * `cmdstan_model()` no longer fails when `MAKEFLAGS` turns on directory
 printing. (#1163)
-* Quoted values in `make/local`'s `STANCFLAGS` now reach `stanc` as one
+* Quoted values in `make/local`'s `STANCFLAGS` now reach stanc as one
 argument. Previously they were split on whitespace. (#1232)
 * `laplace()` no longer overwrites the internally generated optimizer CSV when
 `mode = NULL` and `output_basename` is supplied. The internally generated
@@ -243,7 +243,7 @@ was always 1. (#1187)
 * `$lp_approx()` and `$mle()` now return numeric vectors whatever the
 `cmdstanr_draws_format` option is set to. (#1190)
 * A Stan file name with several spaces, or quotes, now gives a valid model name
-for `stanc`. Previously only the first space was replaced and the quotes ended
+for stanc. Previously only the first space was replaced and the quotes ended
 up in the generated C++. (#1200)
 * `$draws()` on a pathfinder fit now orders the diagnostic columns the same way
 as the other methods. (#1205)

R/args.R

@@ -841,18 +841,18 @@ validate_optimize_args <- function(self) {
     # check that arg is positive or NULL and that algorithm='lbfgs' or 'bfgs' is
     # explicitly specified (error if not or if 'newton')
     if (!is.null(self[[arg]]) && is.null(self$algorithm)) {
-      stop("Please specify 'algorithm' in order to use '", arg, "'.", call. = FALSE)
+      stop("Please specify `algorithm` in order to use `", arg, "`.", call. = FALSE)
     }
     if (!is.null(self[[arg]]) && isTRUE(self$algorithm == "newton")) {
-      stop("'", arg, "' can't be used when algorithm is 'newton'.", call. = FALSE)
+      stop("`", arg, "` can't be used when algorithm is `\"newton\"`.", call. = FALSE)
     }
     checkmate::assert_number(self[[arg]], .var.name = arg, lower = 0, null.ok = TRUE)
   }
 
   # history_size only available for lbfgs
   if (!is.null(self$history_size)) {
     if (!isTRUE(self$algorithm == "lbfgs")) {
-      stop("'history_size' is only allowed if 'algorithm' is specified as 'lbfgs'.", call. = FALSE)
+      stop("`history_size` is only allowed if `algorithm` is specified as `\"lbfgs\"`.", call. = FALSE)
     } else {
       checkmate::assert_integerish(self$history_size, lower = 1, len = 1, null.ok = FALSE)
       self$history_size <- as.integer(self$history_size)
@@ -875,7 +875,7 @@ validate_laplace_args <- function(self) {
   checkmate::assert_flag(self$jacobian, null.ok = FALSE)
   if (self$mode_object$metadata()$jacobian != self$jacobian) {
     stop(
-      "'jacobian' argument to optimize and laplace must match!\n",
+      "`jacobian` argument to optimize and laplace must match!\n",
       "laplace was called with jacobian=", self$jacobian, "\n",
       "optimize was run with jacobian=", as.logical(self$mode_object$metadata()$jacobian),
       call. = FALSE
@@ -1171,13 +1171,13 @@ process_init.list <- function(init, num_procs, model_variables = NULL,
                               warn_partial = getOption("cmdstanr_warn_inits", TRUE),
                               ...) {
   if (!all(sapply(init, function(x) is.list(x) && !is.data.frame(x)))) {
-    stop("If 'init' is a list it must be a list of lists.", call. = FALSE)
+    stop("If `init` is a list it must be a list of lists.", call. = FALSE)
   }
   if (length(init) != num_procs) {
-    stop("'init' has the wrong length. See documentation of 'init' argument.", call. = FALSE)
+    stop("`init` has the wrong length. See documentation of `init` argument.", call. = FALSE)
   }
   if (any(sapply(init, function(x) length(x) == 0))) {
-    stop("'init' contains empty lists.", call. = FALSE)
+    stop("`init` contains empty lists.", call. = FALSE)
   }
   if (!is.null(model_variables)) {
     missing_parameter_values <- list()
@@ -1215,9 +1215,9 @@ process_init.list <- function(init, num_procs, model_variables = NULL,
   }
   if (any(grepl("\\[", names(unlist(init))))) {
     stop(
-      "'init' contains entries with parameter names that include square-brackets, which is not permitted. ",
+      "`init` contains entries with parameter names that include square-brackets, which is not permitted. ",
       "To supply inits for a vector, matrix or array of parameters, ",
-      "create a single entry with the parameter's name in the 'init' list ",
+      "create a single entry with the parameter's name in the `init` list ",
       "and specify initial values for the entire parameter container.",
       call. = FALSE)
   }
@@ -1249,16 +1249,16 @@ process_init.function <- function(init, num_procs, model_variables = NULL,
   has_chain_id <- !is.null(args)
   if (has_chain_id) {
     if (!identical(names(args), "chain_id")) {
-      stop("If 'init' is a function it must have zero arguments ",
-           "or only argument 'chain_id'.", call. = FALSE)
+      stop("If `init` is a function it must have zero arguments ",
+           "or only argument `chain_id`.", call. = FALSE)
     }
   }
 
   init_list <- vector("list", num_procs)
   for (i in seq_len(num_procs)) {
     init_list[[i]] <- if (has_chain_id) init(i) else init()
     if (!is.list(init_list[[i]]) || is.data.frame(init_list[[i]])) {
-      stop("If 'init' is a function it must return a single list.", call. = FALSE)
+      stop("If `init` is a function it must return a single list.", call. = FALSE)
     }
   }
   process_init(init_list, num_procs, model_variables, warn_partial)
@@ -1521,14 +1521,14 @@ validate_init <- function(init, num_procs) {
     return(invisible(TRUE))
   }
   if (!is.numeric(init) && !is.character(init)) {
-    stop("Invalid 'init' specification. See documentation of 'init' argument.",
+    stop("Invalid `init` specification. See documentation of `init` argument.",
          call. = FALSE)
   } else if (is.numeric(init) && (length(init) > 1 || init < 0)) {
-    stop("If 'init' is numeric it must be a single real number >= 0.",
+    stop("If `init` is numeric it must be a single real number >= 0.",
          call. = FALSE)
   } else if (is.character(init)) {
     if (length(init) != 1 && length(init) != num_procs) {
-      stop("If 'init' is specified as a character vector, its length must be ",
+      stop("If `init` is specified as a character vector, its length must be ",
            "1 or equal to the number of chains or Pathfinder paths.",
            call. = FALSE)
     }
@@ -1567,7 +1567,7 @@ validate_seed <- function(seed, num_procs) {
   }
   checkmate::assert_integerish(seed, lower = 0)
   if (length(seed) > 1 && length(seed) != num_procs) {
-    stop("If 'seed' is specified it must be a single integer or one per chain.",
+    stop("If `seed` is specified it must be a single integer or one per chain.",
          call. = FALSE)
   }
   invisible(TRUE)

R/build.R

@@ -253,7 +253,10 @@ install_executable <- function(from, to, record) {
         error_on_status = FALSE
       )
       if (is.na(chmod$status) || chmod$status != 0) {
-        stop("Could not make the compiled executable executable.", call. = FALSE)
+        stop(
+          "Could not set the execute bit on the compiled executable.",
+          call. = FALSE
+        )
       }
     }
     write_build_record(record, candidate)
@@ -355,7 +358,7 @@ inspect_executable <- function(exe_file) {
   features <- reported_features_from_exe(exe_file)
   if (is.null(features[["stan_version"]])) {
     stop(
-      "Running '", exe_file, "' with the argument 'info' did not report a ",
+      "Running '", exe_file, "' with the argument `info` did not report a ",
       "Stan version, so it is either not a CmdStan executable or cannot be ",
       "run.",
       call. = FALSE

R/build_record.R

@@ -157,7 +157,7 @@ validate_build_record <- function(record) {
     option_name <- names(cpp_options)[[i]]
     field <- paste0("configuration.cpp_options.", option_name)
     if (!grepl(paste0("^", make_variable_name_pattern, "$"), option_name)) {
-      stop_build_record_field(field, "must be named for a Make variable")
+      stop_build_record_field(field, "must be named for a make variable")
     }
     assert_record_shape(cpp_options[[i]], "string", field)
   }
@@ -252,7 +252,7 @@ validate_build_record <- function(record) {
 #' The one place a record is built. The fields go in the schema's order so the
 #' written JSON reads that way too.
 #'
-#' @param configuration The options the build used: `cpp_options` as the Make
+#' @param configuration The options the build used: `cpp_options` as the make
 #'   assignments `parsed_cpp_options()` returns, one per name; `stanc_options`,
 #'   `stanc_options_added` and `stanc_options_from_make` as the argument
 #'   vectors stanc receives; `stanc_name`; and `include_paths` as searched.
@@ -681,7 +681,7 @@ assess_build <- function(expected, current) {
 #' When the build record is available, there are four more fields:
 #'
 #' * `configuration`: A list of the options the model was created with.
-#'   * `cpp_options`: the list of options in their Make spelling, as
+#'   * `cpp_options`: the list of options in their make spelling, as
 #'   `$cpp_options()` reports them. For example, `list(stan_threads = TRUE)`
 #'   comes back as `list(STAN_THREADS = "true")`.
 #'   * `stanc_options`: the flags as given to stanc, in order.
@@ -694,14 +694,14 @@ assess_build <- function(expected, current) {
 #'   included files. When none were provided but the Stan program has includes
 #'   this is set to the program's own directory.
 #'
-#' * `dependencies`: A list describing the files the build read. Contains sublists
-#' `stan_file`, `included_files`, `user_header` and `make_local`. `user_header`
-#' and `make_local` are `NULL` when the build had none. `included_files` holds
-#' one entry per file. Each entry has two fields: `built_from`, the path the
-#' file had when the build ran, and `exists`, whether that path exists now. A
-#' path that no longer exists is not necessarily a problem. For example, an \R
-#' package may build its models at install time in a temporary directory that
-#' is gone by the time the model is used.
+#' * `dependencies`: A list describing the files the build read. Contains
+#' sublists `stan_file`, `included_files`, `user_header` and `make_local`.
+#' `user_header` and `make_local` are `NULL` when the build had none.
+#' `included_files` holds one entry per file. Each entry has two fields:
+#' `built_from`, the path the file had when the build ran, and `exists`, whether
+#' that path exists now. A path that no longer exists is not necessarily a
+#' problem. For example, an \R package may build its models at install time in a
+#' temporary directory that is gone by the time the model is used.
 #'
 #' * `cmdstan`: A list containing the `path` and `version` of the CmdStan
 #' installation that built the executable, and whether that path still `exists`.
@@ -710,13 +710,13 @@ assess_build <- function(expected, current) {
 #' release-candidate suffix whereas `reported_features$stan_version` comes from
 #' the Stan library headers the executable was compiled against and will not).
 #'
-#' * `untracked_dependencies`: A list of files the build depended on that CmdStanR
-#' cannot follow, so a change to them does not automatically trigger a rebuild.
-#' An empty list means nothing of the kind was found. Each file is reported as
-#' a sublist with two fields: `kind`, which is `"make_local_include"` when
-#' `make/local` includes another makefile or `"user_header_include"` when the
-#' user header includes other headers, and `detected_in`, the file the include
-#' was found in.
+#' * `untracked_dependencies`: A list of files the build depended on that
+#' CmdStanR cannot follow, so a change to them does not automatically trigger a
+#' rebuild. An empty list means nothing of the kind was found. Each file is
+#' reported as a sublist with two fields: `kind`, which is
+#' `"make_local_include"` when `make/local` includes another makefile or
+#' `"user_header_include"` when the user header includes other headers, and
+#' `detected_in`, the file the include was found in.
 #'
 #' The result leaves out some of what the record holds: the file hashes the
 #' rebuild check compares, the stanc flags CmdStanR added itself, the model

R/cpp_options.R

@@ -7,7 +7,7 @@
 #'
 #' @param cpp_options The user's `cpp_options`, as
 #'   `assert_valid_cpp_options()` returned them.
-#' @return A named list with one value per Make variable.
+#' @return A named list with one value per make variable.
 #' @noRd
 parsed_cpp_options <- function(cpp_options) {
   assignments <- structure(list(), names = character())
@@ -46,7 +46,7 @@ make_variable_name_pattern <- "[A-Za-z_][A-Za-z0-9_]*"
 
 #' Check the `cpp_options` the user supplied and return them
 #'
-#' Every entry must be named and every name must be a Make variable name. The
+#' Every entry must be named and every name must be a make variable name. The
 #' names are uppercased here so that one spelling reaches everything downstream.
 #' The user header and the stanc flags have their own arguments, so setting them
 #' here is an error. A TBB directory has to be a literal path, since the build
@@ -68,7 +68,7 @@ assert_valid_cpp_options <- function(cpp_options) {
     }
     if (!grepl(paste0("^", make_variable_name_pattern, "$"), option_names[[i]])) {
       stop(
-        "`cpp_options` names must be Make variable names, made of letters, ",
+        "`cpp_options` names must be make variable names, made of letters, ",
         "digits and underscores and not starting with a digit. `",
         option_names[[i]], "` is not one.",
         call. = FALSE
@@ -155,7 +155,7 @@ unnamed_cpp_option_message <- function(value) {
   if (grepl("^(-B|--always-make)$", entry)) {
     return(sprintf(
       paste0(
-        "Make flags cannot be passed through `cpp_options`. ",
+        "`cpp_options` cannot pass flags to make. ",
         "`%s` rebuilds everything; pass `force_recompile = TRUE` instead."
       ),
       entry
@@ -166,7 +166,7 @@ unnamed_cpp_option_message <- function(value) {
     path <- sub(makefile_flag_pattern, "\\1", entry)
     return(sprintf(
       paste0(
-        "Make flags cannot be passed through `cpp_options`. ",
+        "`cpp_options` cannot pass flags to make. ",
         "To read another makefile add `include %s` to `make/local`, for example ",
         "`cmdstan_make_local(cpp_options = list(%s))`."
       ),
@@ -175,7 +175,7 @@ unnamed_cpp_option_message <- function(value) {
   }
   if (startsWith(entry, "-")) {
     return(paste0(
-      "Make flags cannot be passed through `cpp_options`. ",
+      "`cpp_options` cannot pass flags to make. ",
       "Set them in `make/local` with `cmdstan_make_local()`, ",
       "for example `MAKEFLAGS += -j4`."
     ))
@@ -240,9 +240,9 @@ assert_valid_threads <- function(threads, features, multiple_chains = FALSE) {
   threaded <- isTRUE(features[["stan_threads"]])
   if (!is.null(threads) && threads > 1 && !threaded) {
     stop(
-      "'", threads_arg, "' is set but the executable does not report ",
+      "`", threads_arg, "` is set but the executable does not report ",
       "threading as enabled.\nRecompile the model with ",
-      "'cpp_options = list(stan_threads = TRUE)'.",
+      "`cpp_options = list(stan_threads = TRUE)`.",
       call. = FALSE
     )
   }
@@ -258,9 +258,9 @@ assert_valid_threads <- function(threads, features, multiple_chains = FALSE) {
 assert_valid_opencl <- function(opencl_ids, features) {
   if (!is.null(opencl_ids) && !isTRUE(features[["stan_opencl"]])) {
     stop(
-      "'opencl_ids' is set but the executable does not report OpenCL as ",
+      "`opencl_ids` is set but the executable does not report OpenCL as ",
       "enabled.\nRecompile the model with ",
-      "'cpp_options = list(stan_opencl = TRUE)'.",
+      "`cpp_options = list(stan_opencl = TRUE)`.",
       call. = FALSE
     )
   }

R/data.R

@@ -92,7 +92,7 @@
 #'
 write_stan_json <- function(data, file, always_decimal = FALSE) {
   if (!is.list(data)) {
-    stop("'data' must be a list.", call. = FALSE)
+    stop("`data` must be a list.", call. = FALSE)
   }
   if (!is.character(file) || !nzchar(file)) {
     stop("The supplied filename is invalid!", call. = FALSE)
@@ -102,11 +102,11 @@ write_stan_json <- function(data, file, always_decimal = FALSE) {
   if (length(data) > 0 &&
       (length(data_names) == 0 ||
        length(data_names) != sum(nzchar(data_names)))) {
-    stop("All elements in 'data' list must have names.", call. = FALSE)
+    stop("All elements in `data` list must have names.", call. = FALSE)
 
   }
   if (anyDuplicated(data_names) != 0) {
-    stop("Duplicate names not allowed in 'data'.", call. = FALSE)
+    stop("Duplicate names not allowed in `data`.", call. = FALSE)
   }
 
   for (var_name in data_names) {
@@ -280,7 +280,7 @@ process_data <- function(data, model_variables = NULL) {
     path <- tempfile(pattern = "standata-", fileext = ".json")
     write_stan_json(data = data, file = path, always_decimal = !is.null(model_variables))
   } else {
-    stop("'data' should be a path or a named list.", call. = FALSE)
+    stop("`data` should be a path or a named list.", call. = FALSE)
   }
   path
 }
@@ -452,7 +452,7 @@ process_fitted_params <- function(fitted_params) {
     paths <- draws_to_csv(posterior::as_draws_array(fitted_params))
   } else {
     stop(
-      "'fitted_params' must be a list of paths to CSV files, ",
+      "`fitted_params` must be a list of paths to CSV files, ",
       "a CmdStanMCMC, CmdStanMLE, CmdStanLaplace, CmdStanVB, or ",
       "CmdStanPathfinder object, ",
       "a posterior::draws_array or a posterior::draws_matrix.", call. = FALSE)