Joins slices_store and slices_restore documentation (#1072)

Related to pre-release activities #1021 

#### Changes description

- [x] merges documentation on `slices_store` & `slices_restore`
- [x] example creates a valid file on disk when run manually (deleted
when the session ends thanks to `{withr}`)
- [x] Q: Should this use the `tmp` directory instead of the current
`wd`?
- `tempfile()` / `withr::local_tempfile()` instead of
`withr::local_file()`

Cons: the `@examples`' code has to be stored in the same tag as
splitting it will remove the file created by `withr` and will fail the
`R CMD check`

---------

Signed-off-by: André Veríssimo <[email protected]>
Co-authored-by: Aleksander Chlebowski <[email protected]>

R/teal_slices-store.R

@@ -1,37 +1,42 @@
-#' Store `teal_slices` object to a file
+#' Store and restore `teal_slices` object
 #'
-#' This function takes a `teal_slices` object and saves it to a file in `JSON` format.
-#' The `teal_slices` object contains information about filter states and can be used to
-#' create, modify, and delete filter states. The saved file can be later loaded using
-#' the `slices_restore` function.
+#' Functions that write a `teal_slices` object to a file in the `JSON` format,
+#' and also restore the object from disk.
 #'
-#' `Date` class is stored in `"ISO8601"` format (`YYYY-MM-DD`). `POSIX*t` classes are converted to a
-#' character by using `format.POSIX*t(usetz = TRUE, tz = "UTC")` (`YYYY-MM-DD {N}{N}:{N}{N}:{N}{N} UTC`, where
-#' `{N} = [0-9]` is a number and `UTC` is `Coordinated Universal Time` timezone short-code).
-#' This format is assumed during `slices_restore`. All `POSIX*t` objects in `selected` or `choices` fields of
-#' `teal_slice` objects are always printed in `UTC` timezone as well.
+#' Date and date time objects are stored in the following formats:
+#'
+#' - `Date` class is converted to the `"ISO8601"` standard (`YYYY-MM-DD`).
+#' - `POSIX*t` classes are converted to character by using
+#' `format.POSIX*t(usetz = TRUE, tz = "UTC")` (`YYYY-MM-DD HH:MM:SS UTC`, where
+#' `UTC` is the `Coordinated Universal Time` timezone short-code).
+#'
+#' This format is assumed during `slices_restore`. All `POSIX*t` objects in
+#' `selected` or `choices` fields of `teal_slice` objects are always printed in
+#' `UTC` timezone as well.
 #'
 #' @param tss (`teal_slices`) object to be stored.
-#' @param file (`character(1)`) The file path where `teal_slices` object will be saved.
-#'  The file extension should be `".json"`.
+#' @param file (`character(1)`) file path where `teal_slices` object will be
+#' saved and restored. The file extension should be `".json"`.
 #'
-#' @return `NULL`, invisibly.
+#' @return `slices_store` returns `NULL`, invisibly.
+#'
+#' @seealso [teal_slices()]
 #'
 #' @examples
 #' # use non-exported function from teal
 #' slices_store <- getFromNamespace("slices_store", "teal")
 #'
 #' # Create a teal_slices object
 #' tss <- teal_slices(
-#'   teal.slice::teal_slice(dataname = "data", varname = "var"),
-#'   teal.slice::teal_slice(dataname = "data", expr = "x > 0", id = "positive_x", title = "Positive x")
+#'   teal_slice(dataname = "data", varname = "var"),
+#'   teal_slice(dataname = "data", expr = "x > 0", id = "positive_x", title = "Positive x")
 #' )
 #'
-#' if (interactive()) {
-#'   # Store the teal_slices object to a file
-#'   slices_store(tss, "path/to/file.json")
-#' }
+#' slices_path <- tempfile(pattern = "teal_slices", fileext = ".json")
+#' print(slices_path)
 #'
+#' # Store the teal_slices object to a file
+#' slices_store(tss, slices_path)
 #' @keywords internal
 #'
 slices_store <- function(tss, file) {
@@ -41,25 +46,17 @@ slices_store <- function(tss, file) {
   cat(format(tss, trim_lines = FALSE), "\n", file = file)
 }
 
-#' Restore `teal_slices` object from a file
-#'
-#' This function takes a file path to a `JSON` file containing a `teal_slices` object
-#' and restores it to its original form. The restored `teal_slices` object can be used
-#' to access filter states and their corresponding attributes.
-#'
-#' @param file Path to file where `teal_slices` is stored. Must have a `.json` extension and read access.
-#'
-#' @return A `teal_slices` object restored from the file.
+#' @rdname slices_store
+#' @return `slices_restore` returns a `teal_slices` object restored from the file.
 #' @examples
+#' 
 #' # use non-exported function from teal
 #' slices_restore <- getFromNamespace("slices_restore", "teal")
 #'
-#' if (interactive()) {
-#'   # Restore a teal_slices object from a file
-#'   tss_restored <- slices_restore("path/to/file.json")
-#' }
-#' @keywords internal
+#' # Restore a teal_slices object from a file
+#' tss_restored <- slices_restore(slices_path)
 #'
+#' @keywords internal
 slices_restore <- function(file) {
   checkmate::assert_file_exists(file, access = "r", extension = "json")
 

inst/WORDLIST

@@ -1,24 +1,25 @@
 Biomarker
-Forkers
-Hoffmann
-MAEs
-Reproducibility
-TLG
-UI
-UIs
-UX
 cloneable
 customizable
 favicon
 favicons
+Forkers
 funder
+Hoffmann
+JSON
+MAEs
 omics
 pre
 programmatically
 repo
+Reproducibility
 reproducibility
 summarization
 tabsetted
 themer
 theming
+TLG
+UI
+UIs
 uncheck
+UX