From 7880c9b7bb3d2c09d8112b5b53291614d4546d39 Mon Sep 17 00:00:00 2001 From: wlandau-lilly Date: Tue, 12 Nov 2024 14:53:34 -0500 Subject: [PATCH] update docs --- R/tar_target.R | 48 +++++++++++++++---------------------------- man/tar_option_set.Rd | 46 +++++++++++++++-------------------------- man/tar_target.Rd | 46 +++++++++++++++-------------------------- 3 files changed, 49 insertions(+), 91 deletions(-) diff --git a/R/tar_target.R b/R/tar_target.R index 52c66755..04fdf091 100644 --- a/R/tar_target.R +++ b/R/tar_target.R @@ -314,43 +314,29 @@ #' functionality, alternative data storage formats, #' and other optional capabilities of `targets`. #' See `tar_resources()` for details. -#' @param storage Character of length 1, only relevant to -#' [tar_make_clustermq()] and [tar_make_future()]. +#' @param storage Character string to control when the output of the target +#' is saved to storage. Only relevant when using `targets` +#' with parallel workers (). #' Must be one of the following values: #' * `"main"`: the target's return value is sent back to the -#' host machine and saved/uploaded locally. +#' host machine and saved/uploaded locally. #' * `"worker"`: the worker saves/uploads the value. -#' * `"none"`: almost never recommended. It is only for -#' niche situations, e.g. the data needs to be loaded -#' explicitly from another language. If you do use it, -#' then the return value of the target is totally ignored -#' when the target ends, but -#' each downstream target still attempts to load the data file -#' (except when `retrieval = "none"`). -#' -#' If you select `storage = "none"`, then -#' the return value of the target's command is ignored, -#' and the data is not saved automatically. -#' As with dynamic files (`format = "file"`) it is the -#' responsibility of the user to write to -#' the data store from inside the target. -#' -#' The distinguishing feature of `storage = "none"` -#' (as opposed to `format = "file"`) -#' is that in the general case, -#' downstream targets will automatically try to load the data -#' from the data store as a dependency. As a corollary, `storage = "none"` -#' is completely unnecessary if `format` is `"file"`. -#' @param retrieval Character of length 1, only relevant to -#' [tar_make_clustermq()] and [tar_make_future()]. +#' * `"none"`: `targets` makes no attempt to save the result +#' of the target to storage in the location where `targets` +#' expects it to be. Saving to storage is the responsibility +#' of the user. Use with caution. +#' @param retrieval Character string to control when the current target +#' loads its dependencies into memory before running. +#' (Here, a "dependency" is another target upstream that the current one +#' depends on.) Only relevant when using `targets` +#' with parallel workers (). #' Must be one of the following values: #' * `"main"`: the target's dependencies are loaded on the host machine #' and sent to the worker before the target runs. -#' * `"worker"`: the worker loads the targets dependencies. -#' * `"none"`: the dependencies are not loaded at all. -#' This choice is almost never recommended. It is only for -#' niche situations, e.g. the data needs to be loaded -#' explicitly from another language. +#' * `"worker"`: the worker loads the target's dependencies. +#' * `"none"`: `targets` makes no attempt to load its +#' dependencies. With `retrieval = "none"`, loading dependencies +#' is the responsibility of the user. Use with caution. #' @param cue An optional object from `tar_cue()` to customize the #' rules that decide whether the target is up to date. #' @param description Character of length 1, a custom free-form human-readable diff --git a/man/tar_option_set.Rd b/man/tar_option_set.Rd index 8e8cc4b3..d0abf44a 100644 --- a/man/tar_option_set.Rd +++ b/man/tar_option_set.Rd @@ -258,47 +258,33 @@ functionality, alternative data storage formats, and other optional capabilities of \code{targets}. See \code{tar_resources()} for details.} -\item{storage}{Character of length 1, only relevant to -\code{\link[=tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[=tar_make_future]{tar_make_future()}}. +\item{storage}{Character string to control when the output of the target +is saved to storage. Only relevant when using \code{targets} +with parallel workers (\url{https://books.ropensci.org/targets/crew.html}). Must be one of the following values: \itemize{ \item \code{"main"}: the target's return value is sent back to the host machine and saved/uploaded locally. \item \code{"worker"}: the worker saves/uploads the value. -\item \code{"none"}: almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. If you do use it, -then the return value of the target is totally ignored -when the target ends, but -each downstream target still attempts to load the data file -(except when \code{retrieval = "none"}). - -If you select \code{storage = "none"}, then -the return value of the target's command is ignored, -and the data is not saved automatically. -As with dynamic files (\code{format = "file"}) it is the -responsibility of the user to write to -the data store from inside the target. - -The distinguishing feature of \code{storage = "none"} -(as opposed to \code{format = "file"}) -is that in the general case, -downstream targets will automatically try to load the data -from the data store as a dependency. As a corollary, \code{storage = "none"} -is completely unnecessary if \code{format} is \code{"file"}. +\item \code{"none"}: \code{targets} makes no attempt to save the result +of the target to storage in the location where \code{targets} +expects it to be. Saving to storage is the responsibility +of the user. Use with caution. }} -\item{retrieval}{Character of length 1, only relevant to -\code{\link[=tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[=tar_make_future]{tar_make_future()}}. +\item{retrieval}{Character string to control when the current target +loads its dependencies into memory before running. +(Here, a "dependency" is another target upstream that the current one +depends on.) Only relevant when using \code{targets} +with parallel workers (\url{https://books.ropensci.org/targets/crew.html}). Must be one of the following values: \itemize{ \item \code{"main"}: the target's dependencies are loaded on the host machine and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. +\item \code{"worker"}: the worker loads the target's dependencies. +\item \code{"none"}: \code{targets} makes no attempt to load its +dependencies. With \code{retrieval = "none"}, loading dependencies +is the responsibility of the user. Use with caution. }} \item{cue}{An optional object from \code{tar_cue()} to customize the diff --git a/man/tar_target.Rd b/man/tar_target.Rd index ac66cf31..4fe0784b 100644 --- a/man/tar_target.Rd +++ b/man/tar_target.Rd @@ -239,47 +239,33 @@ functionality, alternative data storage formats, and other optional capabilities of \code{targets}. See \code{tar_resources()} for details.} -\item{storage}{Character of length 1, only relevant to -\code{\link[=tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[=tar_make_future]{tar_make_future()}}. +\item{storage}{Character string to control when the output of the target +is saved to storage. Only relevant when using \code{targets} +with parallel workers (\url{https://books.ropensci.org/targets/crew.html}). Must be one of the following values: \itemize{ \item \code{"main"}: the target's return value is sent back to the host machine and saved/uploaded locally. \item \code{"worker"}: the worker saves/uploads the value. -\item \code{"none"}: almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. If you do use it, -then the return value of the target is totally ignored -when the target ends, but -each downstream target still attempts to load the data file -(except when \code{retrieval = "none"}). - -If you select \code{storage = "none"}, then -the return value of the target's command is ignored, -and the data is not saved automatically. -As with dynamic files (\code{format = "file"}) it is the -responsibility of the user to write to -the data store from inside the target. - -The distinguishing feature of \code{storage = "none"} -(as opposed to \code{format = "file"}) -is that in the general case, -downstream targets will automatically try to load the data -from the data store as a dependency. As a corollary, \code{storage = "none"} -is completely unnecessary if \code{format} is \code{"file"}. +\item \code{"none"}: \code{targets} makes no attempt to save the result +of the target to storage in the location where \code{targets} +expects it to be. Saving to storage is the responsibility +of the user. Use with caution. }} -\item{retrieval}{Character of length 1, only relevant to -\code{\link[=tar_make_clustermq]{tar_make_clustermq()}} and \code{\link[=tar_make_future]{tar_make_future()}}. +\item{retrieval}{Character string to control when the current target +loads its dependencies into memory before running. +(Here, a "dependency" is another target upstream that the current one +depends on.) Only relevant when using \code{targets} +with parallel workers (\url{https://books.ropensci.org/targets/crew.html}). Must be one of the following values: \itemize{ \item \code{"main"}: the target's dependencies are loaded on the host machine and sent to the worker before the target runs. -\item \code{"worker"}: the worker loads the targets dependencies. -\item \code{"none"}: the dependencies are not loaded at all. -This choice is almost never recommended. It is only for -niche situations, e.g. the data needs to be loaded -explicitly from another language. +\item \code{"worker"}: the worker loads the target's dependencies. +\item \code{"none"}: \code{targets} makes no attempt to load its +dependencies. With \code{retrieval = "none"}, loading dependencies +is the responsibility of the user. Use with caution. }} \item{cue}{An optional object from \code{tar_cue()} to customize the