From 7fa0c07ea8a673ba324e2140d450f4b0021701c4 Mon Sep 17 00:00:00 2001 From: LTLA Date: Mon, 22 Apr 2024 13:56:03 -0700 Subject: [PATCH] Improved documentation for various functions. --- R/fetchDirectory.R | 8 ++++++-- R/fetchManifest.R | 1 + R/listProjects.R | 2 +- man/fetchDirectory.Rd | 12 ++++++++---- man/fetchLatest.Rd | 2 +- man/fetchManifest.Rd | 10 +++++++--- man/fetchPermissions.Rd | 2 +- man/fetchSummary.Rd | 9 ++++++--- man/fetchUsage.Rd | 2 +- man/listAssets.Rd | 2 +- man/listFiles.Rd | 2 +- man/listProjects.Rd | 2 +- man/listVersions.Rd | 2 +- 13 files changed, 36 insertions(+), 20 deletions(-) diff --git a/R/fetchDirectory.R b/R/fetchDirectory.R index 15426f1..3e8ecbf 100644 --- a/R/fetchDirectory.R +++ b/R/fetchDirectory.R @@ -8,11 +8,15 @@ #' @param registry String containing a path to the registry. #' @param url String containing the URL to the Gobbler REST API. #' @param cache String containing a path to a cache directory. -#' If \code{NULL}, an appropriate cache is automatically chosen. +#' If \code{NULL}, an appropriate location is automatically chosen. +#' Only used for remote access. #' @param forceRemote Logical scalar indicating whether to force remote access. -#' This will download all files in the \code{path} via the REST API and cache them locally. +#' This will download all files in the \code{path} via the REST API and cache them locally, +#' even if \code{registry} is on the same filesystem as the caller. #' @param overwrite Logical scalar indicating whether to overwrite the existing cache. +#' Only used for remote access. #' @param concurrent Integer specifying the number of concurrent downloads. +#' Only used for remote access. #' #' @return Path to the subdirectory on the caller's filesystem. #' This is either a path to the registry if it is accessible, diff --git a/R/fetchManifest.R b/R/fetchManifest.R index 26f304d..8e9d415 100644 --- a/R/fetchManifest.R +++ b/R/fetchManifest.R @@ -18,6 +18,7 @@ #' \item \code{md5sum}, a string containing the hex-encoded MD5 checksum of the file. #' \item \code{link} (optional): a list specifying the link destination for a file. #' This contains the strings \code{project}, \code{asset}, \code{version} and \code{path}. +#' If the link destination is itself a link, an \code{ancestor} list will be present that specifies the final location of the file after resolving all intermediate links. #' } #' #' @examples diff --git a/R/listProjects.R b/R/listProjects.R index 37a54a2..3b3c2af 100644 --- a/R/listProjects.R +++ b/R/listProjects.R @@ -6,7 +6,7 @@ #' @param registry String containing a path to the registry. #' @param url String containing the URL to the Gobbler REST API. #' @param forceRemote Logical scalar indicating whether to force remote access via the API, -#' even if \code{registry} is accessible to the caller. +#' even if \code{registry} is on the same filesystem as the caller. #' #' @author Aaron Lun #' diff --git a/man/fetchDirectory.Rd b/man/fetchDirectory.Rd index f9eb65a..6a342b8 100644 --- a/man/fetchDirectory.Rd +++ b/man/fetchDirectory.Rd @@ -23,14 +23,18 @@ This usually takes the form of \code{PROJECT/ASSET/VERSION/*}.} \item{url}{String containing the URL to the Gobbler REST API.} \item{cache}{String containing a path to a cache directory. -If \code{NULL}, an appropriate cache is automatically chosen.} +If \code{NULL}, an appropriate location is automatically chosen. +Only used for remote access.} \item{forceRemote}{Logical scalar indicating whether to force remote access. -This will download all files in the \code{path} via the REST API and cache them locally.} +This will download all files in the \code{path} via the REST API and cache them locally, +even if \code{registry} is on the same filesystem as the caller.} -\item{overwrite}{Logical scalar indicating whether to overwrite the existing cache.} +\item{overwrite}{Logical scalar indicating whether to overwrite the existing cache. +Only used for remote access.} -\item{concurrent}{Integer specifying the number of concurrent downloads.} +\item{concurrent}{Integer specifying the number of concurrent downloads. +Only used for remote access.} } \value{ Path to the subdirectory on the caller's filesystem. diff --git a/man/fetchLatest.Rd b/man/fetchLatest.Rd index 16c381d..7f83af4 100644 --- a/man/fetchLatest.Rd +++ b/man/fetchLatest.Rd @@ -16,7 +16,7 @@ fetchLatest(project, asset, registry, url, forceRemote = FALSE) \item{url}{String containing the URL to the Gobbler REST API.} \item{forceRemote}{Logical scalar indicating whether to force remote access via the API, -even if \code{registry} is accessible to the caller.} +even if \code{registry} is on the same filesystem as the caller.} } \value{ String containing the latest version of the asset. diff --git a/man/fetchManifest.Rd b/man/fetchManifest.Rd index 1c08c8b..1b67831 100644 --- a/man/fetchManifest.Rd +++ b/man/fetchManifest.Rd @@ -27,12 +27,15 @@ fetchManifest( \item{url}{String containing the URL to the Gobbler REST API.} \item{cache}{String containing a path to a cache directory. -If \code{NULL}, an appropriate cache is automatically chosen.} +If \code{NULL}, an appropriate location is automatically chosen. +Only used for remote access.} \item{forceRemote}{Logical scalar indicating whether to force remote access. -This will download all files in the \code{path} via the REST API and cache them locally.} +This will download all files in the \code{path} via the REST API and cache them locally, +even if \code{registry} is on the same filesystem as the caller.} -\item{overwrite}{Logical scalar indicating whether to overwrite the existing cache.} +\item{overwrite}{Logical scalar indicating whether to overwrite the existing cache. +Only used for remote access.} } \value{ List containing the manifest for this version. @@ -43,6 +46,7 @@ The value of each element is another list with the following fields: \item \code{md5sum}, a string containing the hex-encoded MD5 checksum of the file. \item \code{link} (optional): a list specifying the link destination for a file. This contains the strings \code{project}, \code{asset}, \code{version} and \code{path}. +If the link destination is itself a link, an \code{ancestor} list will be present that specifies the final location of the file after resolving all intermediate links. } } \description{ diff --git a/man/fetchPermissions.Rd b/man/fetchPermissions.Rd index 572aee3..7de093a 100644 --- a/man/fetchPermissions.Rd +++ b/man/fetchPermissions.Rd @@ -14,7 +14,7 @@ fetchPermissions(project, registry, url, forceRemote = FALSE) \item{url}{String containing the URL to the Gobbler REST API.} \item{forceRemote}{Logical scalar indicating whether to force remote access via the API, -even if \code{registry} is accessible to the caller.} +even if \code{registry} is on the same filesystem as the caller.} } \value{ List containing the permissions for this project. diff --git a/man/fetchSummary.Rd b/man/fetchSummary.Rd index 4f4b01e..3d39fe5 100644 --- a/man/fetchSummary.Rd +++ b/man/fetchSummary.Rd @@ -27,12 +27,15 @@ fetchSummary( \item{url}{String containing the URL to the Gobbler REST API.} \item{cache}{String containing a path to a cache directory. -If \code{NULL}, an appropriate cache is automatically chosen.} +If \code{NULL}, an appropriate location is automatically chosen. +Only used for remote access.} \item{forceRemote}{Logical scalar indicating whether to force remote access. -This will download all files in the \code{path} via the REST API and cache them locally.} +This will download all files in the \code{path} via the REST API and cache them locally, +even if \code{registry} is on the same filesystem as the caller.} -\item{overwrite}{Logical scalar indicating whether to overwrite the existing cache.} +\item{overwrite}{Logical scalar indicating whether to overwrite the existing cache. +Only used for remote access.} } \value{ List containing the summary for this version, with the following fields: diff --git a/man/fetchUsage.Rd b/man/fetchUsage.Rd index 85428db..b7c5e58 100644 --- a/man/fetchUsage.Rd +++ b/man/fetchUsage.Rd @@ -14,7 +14,7 @@ fetchUsage(project, registry, url, forceRemote = FALSE) \item{url}{String containing the URL to the Gobbler REST API.} \item{forceRemote}{Logical scalar indicating whether to force remote access via the API, -even if \code{registry} is accessible to the caller.} +even if \code{registry} is on the same filesystem as the caller.} } \value{ Numeric scalar specifying the quota usage for the project, in bytes. diff --git a/man/listAssets.Rd b/man/listAssets.Rd index 2e6ee52..21adf95 100644 --- a/man/listAssets.Rd +++ b/man/listAssets.Rd @@ -14,7 +14,7 @@ listAssets(project, registry, url, forceRemote = FALSE) \item{url}{String containing the URL to the Gobbler REST API.} \item{forceRemote}{Logical scalar indicating whether to force remote access via the API, -even if \code{registry} is accessible to the caller.} +even if \code{registry} is on the same filesystem as the caller.} } \value{ Character vector of asset names. diff --git a/man/listFiles.Rd b/man/listFiles.Rd index d782a23..d8935d0 100644 --- a/man/listFiles.Rd +++ b/man/listFiles.Rd @@ -33,7 +33,7 @@ If \code{NULL}, all files associated with this version are listed.} \item{include..}{Logical scalar indicating whether to list files with path components that start with \code{..}.} \item{forceRemote}{Logical scalar indicating whether to force remote access via the API, -even if \code{registry} is accessible to the caller.} +even if \code{registry} is on the same filesystem as the caller.} } \value{ Character vector of relative paths of files associated with the versioned asset. diff --git a/man/listProjects.Rd b/man/listProjects.Rd index 0931373..6b785f3 100644 --- a/man/listProjects.Rd +++ b/man/listProjects.Rd @@ -12,7 +12,7 @@ listProjects(registry, url, forceRemote = FALSE) \item{url}{String containing the URL to the Gobbler REST API.} \item{forceRemote}{Logical scalar indicating whether to force remote access via the API, -even if \code{registry} is accessible to the caller.} +even if \code{registry} is on the same filesystem as the caller.} } \value{ Character vector of project names. diff --git a/man/listVersions.Rd b/man/listVersions.Rd index ad91bcd..58b7fc9 100644 --- a/man/listVersions.Rd +++ b/man/listVersions.Rd @@ -16,7 +16,7 @@ listVersions(project, asset, registry, url, forceRemote = FALSE) \item{url}{String containing the URL to the Gobbler REST API.} \item{forceRemote}{Logical scalar indicating whether to force remote access via the API, -even if \code{registry} is accessible to the caller.} +even if \code{registry} is on the same filesystem as the caller.} } \value{ Character vector of versions.