add extra comments in the examples (#11)

R/prune.R

@@ -1,6 +1,6 @@
 #' Remove data files
 #'
-#' Removes all data (`.tsv` files) from the `path` when they have accompanying metadata (`.yml` file). The metadata remains untouched.
+#' Removes all data (`.tsv` files) from the `path` when they have accompanying metadata (`.yml` file). The metadata remains untouched. See the [workflow](https://inbo.github.io/git2rdata/articles/workflow.html) vignette (`vignette("workflow", package = "git2rdata")`) for some examples on how to use this.
 #' @param path the directory in which to clean all the data files
 #' @param recursive remove files in subdirectories too
 #' @return returns invisibily a vector of removed files names. The paths are
@@ -80,7 +80,7 @@ rm_data.git_repository <- function(
 
 #' Prune metadata files
 #'
-#' Removes all metadata (`.yml` files) from the `path` when they don't have accompanying data (`.tsv` file).
+#' Removes all metadata (`.yml` files) from the `path` when they don't have accompanying data (`.tsv` file). See the [workflow](https://inbo.github.io/git2rdata/articles/workflow.html) vignette (`vignette("workflow", package = "git2rdata")`) for some examples on how to use this.
 #' @inheritParams rm_data
 #' @return returns invisibily a vector of removed files names. The paths are
 #' relative to `root`.

R/recent_commit.R

@@ -10,18 +10,31 @@
 #' @export
 #' @family version_control
 #' @examples
+#' # initialise a git repo using git2r
 #' repo_path <- tempfile("git2rdata-repo")
 #' dir.create(repo_path)
 #' repo <- git2r::init(repo_path)
 #' git2r::config(repo, user.name = "Alice", user.email = "alice@example.org")
+#'
+#' # write and commit a first dataframe
 #' write_vc(iris[1:6, ], "iris", repo, sorting = "Sepal.Length", stage = TRUE)
 #' commit(repo, "important analysis", session = TRUE)
+#' list.files(repo_path)
 #' Sys.sleep(1.1) # required because git doesn't handle subsecond timings
+#'
+#' # write and commit a second dataframe
 #' write_vc(iris[7:12, ], "iris2", repo, sorting = "Sepal.Length", stage = TRUE)
 #' commit(repo, "important analysis", session = TRUE)
+#' list.files(repo_path)
 #' Sys.sleep(1.1) # required because git doesn't handle subsecond timings
+#'
+#' # write and commit a new version of the first dataframe
 #' write_vc(iris[7:12, ], "iris", repo, stage = TRUE)
+#' list.files(repo_path)
 #' commit(repo, "important analysis", session = TRUE)
+#'
+#' # find out in which commit a file was last changed
+#'
 #' # "iris.tsv" was last updated in the third commit
 #' recent_commit("iris.tsv", repo)
 #' # "iris.yml" was last updated in the first commit
@@ -30,9 +43,12 @@
 #' recent_commit("iris2.yml", repo)
 #' # the data object "iris" was last updated in the third commit
 #' recent_commit("iris", repo, data = TRUE)
+#'
+#' # remove a dataframe and commit it
 #' file.remove(file.path(repo_path, "iris.tsv"))
 #' prune_meta(repo, ".")
 #' commit(repo, message = "remove iris", all = TRUE, session = TRUE)
+#'
 #' # still points to the third commit as it is the latest commit in which the
 #' # data was present
 #' recent_commit("iris", repo, data = TRUE)

R/relabel.R

@@ -14,19 +14,26 @@
 #' @return invisible `NULL`
 #' @export
 #' @examples
+#'
+#' # setup a directory
 #' root <- tempfile("git2rdata-relabel")
 #' dir.create(root)
+#'
+#' # create a dataframe and store it
 #' ds <- ds <- data.frame(a = c("a1", "a2"), b = c("b2", "b1"))
 #' write_vc(ds, "relabel", root, sorting = "b")
+#'
+#' # define new labels as a list and apply them
 #' new_labels <- list(
 #'   a = list(a2 = "a3")
 #' )
 #' relabel("relabel", root, new_labels)
+#'
+#' # define new labels as a dataframe and apply them
 #' change <- data.frame(
 #'   factor = c("a", "a", "b"),
 #'   old = c("a3", "a1", "b2"),
-#'   new = c("c2", "c1", "b3"),
-#'   stringsAsFactors = FALSE
+#'   new = c("c2", "c1", "b3")
 #' )
 #' relabel("relabel", root, change)
 #' @family storage

man-roxygen/example-io.R

@@ -1,42 +1,68 @@
 #' @examples
-#' # on file system
+#' ## on file system
+#'
+#' # create a directory
 #' root <- tempfile("git2rdata-")
 #' dir.create(root)
+#'
+#' # write a dataframe to the directory
 #' write_vc(iris[1:6, ], file = "iris", root = root, sorting = "Sepal.Length")
+#' # check that a data file (.tsv) and a meta data file (.yml) are created
 #' list.files(root, recursive = TRUE)
+#' # read the data from the directory
 #' read_vc("iris", root)
+#'
+#' # store a new version
 #' write_vc(iris[1:5, ], "iris", root)
 #' list.files(root, recursive = TRUE)
+#' # store a new version in case the meta data must change
 #' write_vc(
 #'   iris[1:6, -2], "iris", root, sorting = "Sepal.Length", strict = FALSE
 #' )
 #' list.files(root, recursive = TRUE)
+#' # storing the first version again required another update of the meta data
 #' write_vc(iris[1:6, ], "iris", root, sorting = "Sepal.Width", strict = FALSE)
 #' list.files(root, recursive = TRUE)
+#' # storing the data in verbose format leads to larger files
 #' write_vc(
 #'   iris[1:6, ], "iris2", root, sorting = "Sepal.Width", optimize = FALSE
 #' )
 #' list.files(root, recursive = TRUE)
 #'
-#' # on git repo
+#'
+#'
+#' ## on git repo
+#'
+#' # initialise a git repo using the git2r package
 #' repo_path <- tempfile("git2rdata-repo-")
 #' dir.create(repo_path)
 #' repo <- git2r::init(repo_path)
 #' git2r::config(repo, user.name = "Alice", user.email = "alice@example.org")
+#'
+#' # store a dataframe in git repo
 #' write_vc(iris[1:6, ], file = "iris", root = repo, sorting = "Sepal.Length")
 #' status(repo)
+#' # read a dataframe from a git repo
 #' read_vc("iris", repo)
+#'
+#' # store a new version of in the git repo
 #' write_vc(iris[1:5, ], "iris", repo, stage = TRUE)
 #' status(repo)
+#'
+#' # store a version with altered meta data
 #' write_vc(
 #'   iris[1:6, -2], "iris", repo, sorting = "Sepal.Length", strict = FALSE
 #' )
 #' status(repo)
+#'
+#' # store the original version again
 #' write_vc(
 #'   iris[1:6, ], "iris", repo, sorting = "Sepal.Width", strict = FALSE,
 #'   stage = TRUE
 #' )
 #' status(repo)
+#'
+#' # store a verbose version in separate files
 #' write_vc(
 #'   iris[1:6, ], "iris2", repo, sorting = "Sepal.Width", optimize = FALSE
 #' )

man-roxygen/example-prune.R

@@ -1,30 +1,55 @@
 #' @examples
-#' # on file system
+#' ## on file system
+#'
+#' # create a directory
 #' root <- tempfile("git2rdata-")
 #' dir.create(root)
+#'
+#' # store a dataframe
 #' write_vc(iris[1:6, ], "iris", root, sorting = "Sepal.Length")
+#' # list the available data and the files
 #' list_data(root)
 #' list.files(root, recursive = TRUE)
+#'
+#' # remove all .tsv files with an associated .yml file
 #' rm_data(root, path = ".")
+#' # check the removal of the data
 #' list.files(root, recursive = TRUE)
 #' list_data(root)
+#'
+#' # remove dangling meta data files
 #' prune_meta(root, path = ".")
+#' # check the removal of the meta data
 #' list.files(root, recursive = TRUE)
 #' list_data(root)
 #'
-#' # on git repo
+#'
+#' ## on git repo
+#'
+#' # initialise a git repo using git2r
 #' repo_path <- tempfile("git2rdata-repo-")
 #' dir.create(repo_path)
 #' repo <- git2r::init(repo_path)
 #' git2r::config(repo, user.name = "Alice", user.email = "alice@example.org")
+#'
+#' # store a dataframe
 #' write_vc(iris[1:6, ], "iris", repo, sorting = "Sepal.Length", stage = TRUE)
+#' # check that the dataframe is stored
 #' status(repo)
 #' list_data(repo)
+#'
+#' # commit the current version and check the git repo
 #' commit(repo, "add iris data", session = TRUE)
 #' status(repo)
+#'
+#' # remove the data files from the repo
 #' rm_data(repo, path = ".")
+#' # check the removal
 #' list_data(repo)
 #' status(repo)
+#'
+#' # remove dangling meta data
 #' prune_meta(repo, path = ".")
+#' # check the removal
 #' list_data(repo)
 #' status(repo)