improve docs, examples and messaging

R/consent.R

@@ -24,6 +24,13 @@
 #' @return `TRUE` if consent is given, otherwise an error is raised.
 #' 
 #' @export
+#' @examples
+#' \dontrun{
+#' 
+#' # to provide consent and prevent other functions from interrupting to get the consent
+#' rje_consent(provided = TRUE)
+#' }
+#' 
 rje_consent <- function(provided = FALSE) {
 
   # Check if consent is already given via environment variable

R/java_manage.R

@@ -1,17 +1,28 @@
-#' List the contents of the Java cache
+#' List the contents of the Java versions installed or cached
 #'
-#' @param type The type of cache to list: "distrib", "installed", or "project".
-#' @param output The format of the output: "data.frame" or "vector". Defaults to "data.frame".
+#' @description
+#' This function lists one of the following:
+#' 
+#' * `project` - list the contents of the Java symlinked/copied in the current project or directory specified by `target_dir`
+#' 
+#'  * `distrib` - list the contents of the downloaded Java distributions cache in default location or specified by `target_dir`
+#' 
+#'  * `installed` - list the contents of the Java installations cache (unpacked distributions) in default location or specified by `target_dir`
+#' 
+#' @param type The type of cache to list: "distrib", "installed", or "project". Defaults to "project".
+#' @param output The format of the output: `data.frame`` or `vector``. Defaults to `data.frame`.
 #' @inheritParams global_quiet_param
 #' @param target_dir The cache directory to list. Defaults to the user-specific data directory for "distrib" and "installed", and the current working directory for "project".
-#' @return A data frame or character vector with the contents of the specified cache directory.
+#' @return A `dataframe` or `character` `vector` with the contents of the specified cache or project directory.
 #' @export
 #'
 #' @examples
+#' \dontrun{
 #' java_list("project")
 #' java_list("installed")
 #' java_list("distrib")
-#'
+#'}
+#' 
 java_list <- function(
     type = c("project", "installed", "distrib"),
     output = c("data.frame", "vector"),
@@ -24,7 +35,7 @@ java_list <- function(
     if (type == "project") {
       target_dir <- getwd()
     } else {
-      target_dir <- tools::R_user_dir("rJavaEnv", which = "cache")
+      target_dir <- getOption("rJavaEnv.cache_path")
     }
   }
 
@@ -49,9 +60,11 @@ java_list <- function(
 #' @export
 #'
 #' @examples
+#' \dontrun{
 #' java_clear("project")
 #' java_clear("installed")
 #' java_clear("distrib")
+#' }
 #'
 java_clear <- function(
     type = c("project", "installed", "distrib"),

R/java_manage_distrib_cache.R

@@ -6,11 +6,7 @@
 #' @inheritParams global_quiet_param
 #' @return A character vector with the contents of the cache directory.
 #'
-#' @examples
-#' \dontrun{
-#' java_list_distrib_cache()
-#' }
-#'
+#' @keywords internal
 java_list_distrib_cache <- function(
   cache_path = getOption("rJavaEnv.cache_path"),
   output = c("data.frame", "vector"),
@@ -21,7 +17,7 @@ java_list_distrib_cache <- function(
   cache_path <- file.path(cache_path, "distrib")
 
   if (!dir.exists(cache_path)) {
-    cli::cli_alert_danger("Path does not exist")
+    cli::cli_alert_danger("No Java distributions have been downloaded.")
     return(character(0))
   }
   if (!quiet) cli::cli_inform("Contents of the Java distributions cache folder:")
@@ -48,17 +44,7 @@ java_list_distrib_cache <- function(
 #' @inheritParams java_download
 #' @return A message indicating whether the cache was cleared or not.
 #'
-#' @examples
-#' \dontrun{
-#' # delete all cached distributions
-#' # if you leave `cache_path` empty, the function
-#' # will clear in the package cache in your default user space cache
-#' java_clear_distrib_cache(
-#'   cache_path = tempdir(),
-#'   check = FALSE,
-#'   delete_all = TRUE
-#' )
-#' }
+#' @keywords internal
 java_clear_distrib_cache <- function(
   cache_path = getOption("rJavaEnv.cache_path"),
   check = TRUE,

R/java_manage_installed_cache.R

@@ -4,12 +4,7 @@
 #' @param cache_path The cache directory to list. Defaults to the user-specific data directory. Not recommended to change.
 #' @inheritParams global_quiet_param
 #' @return A data frame or character vector with the contents of the cache directory.
-#'
-#' @examples
-#' \dontrun{
-#' java_list_installed_cache()
-#' }
-#'
+#' @keywords internal
 java_list_installed_cache <- function(
     output = c("data.frame", "vector"),
     quiet = TRUE,
@@ -19,7 +14,7 @@ java_list_installed_cache <- function(
   installed_cache_path <- file.path(cache_path, "installed")
 
   if (!dir.exists(installed_cache_path)) {
-    cli::cli_alert_danger("Path does not exist")
+    cli::cli_alert_danger("No Java distributions have been installed yet.")
     return(character(0))
   }
 
@@ -59,10 +54,7 @@ java_list_installed_cache <- function(
 #' @param delete_all Whether to delete all installations without prompting. Defaults to FALSE.
 #' @return A message indicating whether the cache was cleared or not.
 #'
-#' @examples
-#' \dontrun{
-#' java_clear_installed_cache()
-#' }
+#' @keywords internal
 java_clear_installed_cache <- function(
     check = TRUE,
     delete_all = FALSE,

R/java_manage_project.R

@@ -4,7 +4,7 @@
 #' @param output The format of the output: "data.frame" or "vector". Defaults to "data.frame".
 #' @inheritParams global_quiet_param
 #' @return A data frame or character vector with the symlinked Java versions in the project directory.
-#'
+#' @keywords internal
 java_list_in_project <- function(
     project_path = NULL,
     output = c("data.frame", "vector"),
@@ -61,11 +61,8 @@ java_list_in_project <- function(
 #' @param check Whether to list the symlinked Java versions before clearing them. Defaults to TRUE.
 #' @param delete_all Whether to delete all symlinks without prompting. Defaults to FALSE.
 #' @return A message indicating whether the symlinks were cleared or not.
-#'
-#' @examples
-#' \dontrun{
-#' java_clear_in_project()
-#' }
+#' 
+#' @keywords internal
 java_clear_in_project <- function(
     project_path = NULL,
     check = TRUE,