docs: add links to package man throughout

Author: eli-daniels

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: workspace
 Title: Manage Collections of Datasets and Objects
-Version: 0.1.5.002
+Version: 0.1.5.003
 Authors@R: c(
     person("Eli", "Daniels", , "[email protected]", role = c("aut", "cre")),
     person("David", "Gohel", , "[email protected]", role = "aut"),

R/readers.R

@@ -4,7 +4,12 @@
 #' List all objects stored in a workspace object and
 #' returns results as a tibble.
 #' @param x the workspace
-#' @return Tibble listing workspace contents.
+#' @return Tibble object containing the following columns:
+#' -  `file`: file path to stored object relative to workspace directory
+#' -  `name`: name given to object upon storing
+#' -  `subdir`: subdirectory of file, such as 'datasets' or 'assets'.
+#' -  `type`: file type such as 'dataset', 'geospatial', 'yaml', etc...
+#' -  `timestamp`: timestamp of last modification
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -13,6 +18,7 @@
 #' z <- store_dataset(x = z, dataset = mtcars, name = "mtcars")
 #' list_object_in_workspace(z)
 #' @family functions to read in a workspace
+#' @seealso [workspace] for package documentation
 list_object_in_workspace <- function(x) {
   objects_descriptions <- read_objects_description(x)
   objects_descriptions
@@ -26,8 +32,9 @@ list_object_in_workspace <- function(x) {
 #' in a workspace.
 #' @param x the workspace
 #' @param name name of the dataset stored in the workspace
-#' @return a `tibble` if the dataset is stored as parquet, and a
-#' `sf` object if it is stored as a geospatial dataset.
+#' @return A `tibble` if the dataset is stored as parquet, and a
+#' `sf` object if it is stored as a geospatial dataset
+#' (see [store_dataset()] for details).
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -36,6 +43,7 @@ list_object_in_workspace <- function(x) {
 #' z <- store_dataset(x = z, dataset = mtcars, name = "mtcars")
 #' read_dataset_in_workspace(z, name = "mtcars")
 #' @family functions to read in a workspace
+#' @seealso [workspace] for package documentation
 read_dataset_in_workspace <- function(x, name) {
   objs <- list_object_in_workspace(x)
   objs <- objs[objs$type %in% c("dataset", "geospatial"), ]
@@ -85,7 +93,7 @@ read_dataset_in_workspace <- function(x, name) {
 #' Read a raster dataset stored as a TIFF file in a workspace.
 #' @param x the workspace object
 #' @param name name of the raster dataset stored in the workspace
-#' @return a `splatRaster` object
+#' @return The `splatRaster` object that was stored in TIFF format.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -98,6 +106,7 @@ read_dataset_in_workspace <- function(x, name) {
 #'   retrieved_raster
 #' }
 #' @family functions to read in a workspace
+#' @seealso [workspace] for package documentation
 read_raster_in_workspace <- function(x, name) {
 
   if (!requireNamespace("terra", quietly = TRUE)) {
@@ -146,7 +155,7 @@ read_raster_in_workspace <- function(x, name) {
 #' @param x the workspace
 #' @param name name of the object stored in the workspace
 #' @param subdir Optional subdirectory used for the asset to retrieve
-#' @return the R object
+#' @return the R object that was stored as an Rds file.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -161,6 +170,7 @@ read_raster_in_workspace <- function(x, name) {
 #' )
 #' read_rds_in_workspace(z, name = "obj")
 #' @family functions to read in a workspace
+#' @seealso [workspace] for package documentation
 read_rds_in_workspace <- function(x, name, subdir = NULL) {
   objs <- list_object_in_workspace(x)
   objs <- objs[objs$type %in% "rds", ]
@@ -188,7 +198,7 @@ read_rds_in_workspace <- function(x, name, subdir = NULL) {
 #' @param x the workspace
 #' @param name name associated with the json file stored in the workspace
 #' @param subdir Optional subdirectory used for the asset to retrieve
-#' @return a character string containing the JSON string.
+#' @return A character string containing the JSON string.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -209,6 +219,7 @@ read_rds_in_workspace <- function(x, name, subdir = NULL) {
 #' )
 #' read_json_str_in_workspace(z, "an_example")
 #' @family functions to read in a workspace
+#' @seealso [workspace] for package documentation
 read_json_str_in_workspace <- function(x, name, subdir = NULL) {
   objs <- list_object_in_workspace(x)
   objs <- objs[objs$type %in% "json", ]
@@ -242,7 +253,7 @@ read_json_str_in_workspace <- function(x, name, subdir = NULL) {
 #' @param x the workspace
 #' @param name name associated with the YAML file stored in the workspace
 #' @param subdir Optional subdirectory used for the asset to retrieve
-#' @return a list
+#' @return A list object as read from the stored YAML file.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -268,6 +279,7 @@ read_json_str_in_workspace <- function(x, name, subdir = NULL) {
 #' )
 #' read_yaml_in_workspace(z, "app_config", subdir = "configs")
 #' @family functions to read in a workspace
+#' @seealso [workspace] for package documentation
 read_yaml_in_workspace <- function(x, name, subdir = NULL) {
 
   objs <- list_object_in_workspace(x)
@@ -295,14 +307,15 @@ read_yaml_in_workspace <- function(x, name, subdir = NULL) {
 
 
 #' @export
-#' @title Read Timestamp associated with a content of a Workspace.
+#' @title Read Timestamp associated with an object in a workspace.
 #' @description
-#' Read a timestamp associated with a content located in a Workspace.
+#' Read a timestamp associated with an object in a workspace.
 #' @param x the workspace
 #' @param name name of the object stored in the workspace
 #' @param type content type
 #' @param subdir Optional subdirectory used for the asset to retrieve
-#' @return character string of timestamp
+#' @return A character string corresponding to the timestamp (date last modified)
+#' of the stored object.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -317,6 +330,7 @@ read_yaml_in_workspace <- function(x, name, subdir = NULL) {
 #' )
 #' read_timestamp(z, name = "obj", type = "rds", subdir = "r-object")
 #' @family functions to read in a workspace
+#' @seealso [workspace] for package documentation
 read_timestamp <- function(x, name, type, subdir = NULL) {
   objs <- list_object_in_workspace(x)
   objs <- objs[objs$type %in% type, ]

R/rm.R

@@ -7,7 +7,7 @@
 #' @param name name of the object stored in the workspace
 #' @param type content type
 #' @param subdir Optional subdirectory used for the asset to retrieve
-#' @return workspace object resulting from operation.
+#' @return Returns the [workspace] object passed to `x` parameter. Called primarily for side effects.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -38,6 +38,7 @@
 #'   type = "rds",
 #'   subdir = "r-object"
 #' )
+#' @seealso [workspace] for package documentation
 rm_object_in_workspace <- function(x, name, type, subdir = NULL) {
 
   objects_desc <- list_object_in_workspace(x)
@@ -90,7 +91,7 @@ rm_object_in_workspace <- function(x, name, type, subdir = NULL) {
 #' This function removes the dataset file and updates the workspace's object descriptions.
 #' @param x The workspace object.
 #' @param data_name The name of the dataset to delete from the workspace.
-#' @return return the workspace object
+#' @return Returns the [workspace] object passed to `x` parameter. Called primarily for side effects.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -100,6 +101,7 @@ rm_object_in_workspace <- function(x, name, type, subdir = NULL) {
 #' z <- delete_dataset(x = z, data_name = "iris_dataset")
 #' z
 #' @family functions to write in a workspace
+#' @seealso [workspace] for package documentation
 delete_dataset <- function(x, data_name) {
 
   base_file <- stri_trans_general(data_name, id = "latin-ascii")

R/store.R

@@ -26,7 +26,7 @@
 #' already it will be replaced. The name is translated to ascii using
 #' [stringi::stri_trans_general()] to avoid file naming issues.
 #' @param timestamp A timestamp string to associate with the entry in the workspace.
-#' @return Returns the workspace object passed to `x`, now containing the new dataset.
+#' @return Returns the [workspace] object passed to `x` parameter. Called primarily for side effects.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -35,6 +35,7 @@
 #' z <- store_dataset(x = z, dataset = mtcars, name = "mtcars")
 #' z
 #' @family functions to write in a workspace
+#' @seealso [workspace] for package documentation
 store_dataset <- function(x, dataset, name, timestamp = format(Sys.time(), "%Y-%m-%d %H:%M:%S")) {
   UseMethod("store_dataset", dataset)
 }
@@ -124,7 +125,7 @@ store_dataset.sf <- function(x, dataset, name, timestamp = format(Sys.time(), "%
 #' @param name name associated with the SpatRaster, if a workspace file with this name exists
 #' already it will be replaced.
 #' @param timestamp A timestamp string to associate with the entry in the workspace.
-#' @return Returns the workspace object passed to `x`, now containing the new raster file.
+#' @return Returns the [workspace] object passed to `x` parameter. Called primarily for side effects.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -136,6 +137,7 @@ store_dataset.sf <- function(x, dataset, name, timestamp = format(Sys.time(), "%
 #'   z
 #' }
 #' @family functions to write in a workspace
+#' @seealso [workspace] for package documentation
 store_raster <- function(x, dataset, name, timestamp = format(Sys.time(), "%Y-%m-%d %H:%M:%S")) {
 
   if (!requireNamespace("terra", quietly = TRUE)) {
@@ -200,7 +202,7 @@ store_dataset.SpatRaster <- function(x, dataset, name, timestamp = format(Sys.ti
 #' already it will be replaced.
 #' @param timestamp A timestamp string to associate with the entry in the workspace.
 #' @param subdir A subdirectory within the asset directory where the JSON file will be stored.
-#' @return return the workspace object
+#' @return Returns the [workspace] object passed to `x` parameter. Called primarily for side effects.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -219,6 +221,7 @@ store_dataset.SpatRaster <- function(x, dataset, name, timestamp = format(Sys.ti
 #' )
 #' z
 #' @family functions to write in a workspace
+#' @seealso [workspace] for package documentation
 store_json <- function(x, json_str, filename, name = NULL, subdir, timestamp = format(Sys.time(), "%Y-%m-%d %H:%M:%S")) {
 
   if (!is_string(json_str)) {
@@ -282,7 +285,7 @@ store_json <- function(x, json_str, filename, name = NULL, subdir, timestamp = f
 #' already it will be replaced.
 #' @param timestamp A timestamp string to associate with the entry in the workspace.
 #' @param subdir A subdirectory within the asset directory where the RDS file will be stored.
-#' @return return the workspace object
+#' @return Returns the [workspace] object passed to `x` parameter. Called primarily for side effects.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -296,6 +299,7 @@ store_json <- function(x, json_str, filename, name = NULL, subdir, timestamp = f
 #' )
 #' z
 #' @family functions to write in a workspace
+#' @seealso [workspace] for package documentation
 store_rds <- function(x, obj, filename, name = NULL, subdir, timestamp = format(Sys.time(), "%Y-%m-%d %H:%M:%S")) {
 
   if (!is_string(filename)) {
@@ -358,7 +362,7 @@ store_rds <- function(x, obj, filename, name = NULL, subdir, timestamp = format(
 #' already it will be replaced.
 #' @param timestamp A timestamp string to associate with the entry in the workspace.
 #' @param subdir A subdirectory within the asset directory where the YAML file will be stored.
-#' @return return the workspace object with new YAML file.
+#' @return Returns the [workspace] object passed to `x` parameter. Called primarily for side effects.
 #' @examples
 #' library(workspace)
 #' dir_tmp <- tempfile(pattern = "ws")
@@ -384,6 +388,7 @@ store_rds <- function(x, obj, filename, name = NULL, subdir, timestamp = format(
 #' )
 #' z
 #' @family functions to write in a workspace
+#' @seealso [workspace] for package documentation
 store_yaml <- function(x, list, filename, name = NULL, subdir, timestamp = format(Sys.time(), "%Y-%m-%d %H:%M:%S")) {
 
   if (!inherits(list, 'list')) {

R/workspace.R

@@ -76,6 +76,7 @@ as_workspace_structure <- function(dir, obj_desc, version) {
 #' z <- new_workspace()
 #' z
 #' @family functions to manage workspaces
+#' @seealso [workspace] for package documentation
 new_workspace <- function(dir = tempfile(pattern = "ws")) {
 
   if (dir.exists(dir)) {
@@ -132,6 +133,7 @@ new_workspace <- function(dir = tempfile(pattern = "ws")) {
 #' file <- tempfile(fileext = ".zip")
 #' pack_workspace(x = z, file = file)
 #' @family functions to manage workspaces
+#' @seealso [workspace] for package documentation
 pack_workspace <- function(x, file) {
   pack_folder(x$dir, target = file)
 }
@@ -175,6 +177,7 @@ pack_workspace <- function(x, file) {
 #' z <- unpack_workspace(file = file)
 #' z
 #' @family functions to manage workspaces
+#' @seealso [workspace] for package documentation
 unpack_workspace <- function(file) {
 
   dir <- tempfile(pattern = "ws")
@@ -316,6 +319,7 @@ print.workspace <- function(x, ...) {
 #'
 #' new_z <- workspace_copy(z)
 #' @family functions to manage workspaces
+#' @seealso [workspace] for package documentation
 workspace_copy <- function(x) {
   file <- tempfile(fileext = ".zip")
   pack_workspace(x = x, file = file)
@@ -364,6 +368,7 @@ workspace_copy <- function(x) {
 #' new_x <- workspace_bind(x, z)
 #' new_x
 #' @family functions to manage workspaces
+#' @seealso [workspace] for package documentation
 workspace_bind <- function(x, y, replace = FALSE) {
 
   if (!inherits(x, "workspace")) {