documentation pass 3

NAMESPACE

@@ -39,9 +39,9 @@ export(download_azure_file)
 export(download_blob)
 export(download_from_url)
 export(file_share)
-export(get_azure_blob_properties)
 export(get_azure_dir_properties)
 export(get_azure_file_properties)
+export(get_blob_properties)
 export(get_storage_properties)
 export(list_azure_files)
 export(list_blob_containers)

R/blob_client_funcs.R

@@ -3,7 +3,7 @@
 #' Get, list, create, or delete blob containers.
 #'
 #' @param endpoint Either a blob endpoint object as created by [storage_endpoint], or a character string giving the URL of the endpoint.
-#' @param key, sas If an endpoint object is not supplied, authentication details. If neither an access key nor a SAS are provided, only public (anonymous) access to the share is possible.
+#' @param key,sas If an endpoint object is not supplied, authentication details. If neither an access key nor a SAS are provided, only public (anonymous) access to the share is possible.
 #' @param api_version If an endpoint object is not supplied, the storage API version to use when interacting with the host. Currently defaults to `"2017-07-29"`.
 #' @param name The name of the blob container to get, create, or delete.
 #' @param confirm For deleting a container, whether to ask for confirmation.
@@ -167,7 +167,7 @@ delete_blob_container.blob_endpoint <- function(endpoint, name, confirm=TRUE, le
 #'
 #' @param container A blob container object.
 #' @param blob A string naming a blob.
-#' @param src, dest The source and destination filenames for uploading and downloading. Paths are allowed.
+#' @param src,dest The source and destination filenames for uploading and downloading. Paths are allowed.
 #' @param confirm Whether to ask for confirmation on deleting a blob.
 #'
 #' @return

R/blob_lease.R

@@ -1,3 +1,26 @@
+#' Operations on blob leases
+#'
+#' Manage leases for blobs and blob containers.
+#'
+#' @param container A blob container object.
+#' @param blob The name of an individual blob. If not supplied, the lease applies to the entire container.
+#' @param duration For `acquire_lease`, The duration of the requested lease. For an indefinite duration, set this to -1.
+#' @param lease For `acquire_lease` an optional proposed name of the lease; for `release_lease`, `renew_lease` and `change_lease`, the name of the existing lease.
+#' @param period For `break_lease`, the period for which to break the lease.
+#' @param new_lease For `change_lease`, the proposed name of the lease.
+#'
+#' @details
+#' Leasing is a way to prevent a blob or container from being accidentally deleted. The duration of a lease can range from 15 to 60 seconds, or be indefinite.
+#'
+#' @return
+#' For `acquire_lease` and `change_lease`, a string containing the lease ID.
+#'
+#' @seealso
+#' [blob_container],
+#' [Leasing a blob](https://docs.microsoft.com/en-us/rest/api/storageservices/lease-blob),
+#' [Leasing a container](https://docs.microsoft.com/en-us/rest/api/storageservices/lease-container)
+#'
+#' @rdname lease
 #' @export
 acquire_lease <- function(container, blob="", duration=60, lease=NULL)
 {
@@ -11,6 +34,7 @@ acquire_lease <- function(container, blob="", duration=60, lease=NULL)
 }
 
 
+#' @rdname lease
 #' @export
 break_lease <- function(container, blob="", period=NULL)
 {
@@ -22,6 +46,7 @@ break_lease <- function(container, blob="", period=NULL)
 }
 
 
+#' @rdname lease
 #' @export
 release_lease <- function(container, blob="", lease)
 {
@@ -31,6 +56,7 @@ release_lease <- function(container, blob="", lease)
 }
 
 
+#' @rdname lease
 #' @export
 renew_lease <- function(container, blob="", lease)
 {
@@ -40,6 +66,7 @@ renew_lease <- function(container, blob="", lease)
 }
 
 
+#' @rdname lease
 #' @export
 change_lease <- function(container, blob="", lease, new_lease)
 {

R/client.R

@@ -52,7 +52,7 @@ print.storage_endpoint <- function(object)
 
 #' Generic upload and download
 #'
-#' @param src, dest The source and destination files/URLs. Paths are allowed.
+#' @param src,dest The source and destination files/URLs. Paths are allowed.
 #' @param ... Further arguments to pass to lower-level functions. In particular, use `key` and/or `sas` to supply an access key or SAS. Without a key or SAS, only unauthenticated (anonymous) access is possible.
 #' @param overwrite For downloading, whether to overwrite any destination files that exist.
 #'

R/file_client_funcs.R

@@ -3,7 +3,7 @@
 #' Get, list, create, or delete file shares.
 #'
 #' @param endpoint Either a file endpoint object as created by [storage_endpoint], or a character string giving the URL of the endpoint.
-#' @param key, sas If an endpoint object is not supplied, authentication details. If neither an access key nor a SAS are provided, only public (anonymous) access to the share is possible.
+#' @param key,sas If an endpoint object is not supplied, authentication details. If neither an access key nor a SAS are provided, only public (anonymous) access to the share is possible.
 #' @param api_version If an endpoint object is not supplied, the storage API version to use when interacting with the host. Currently defaults to `"2017-07-29"`.
 #' @param name The name of the file share to get, create, or delete.
 #' @param confirm For deleting a share, whether to ask for confirmation.
@@ -157,9 +157,9 @@ delete_file_share.file_endpoint <- function(endpoint, name, confirm=TRUE)
 #' Upload, download, or delete a file; list files in a directory; create or delete directories.
 #'
 #' @param share A file share object.
-#' @param dir, file A string naming a directory or file respectively.
+#' @param dir,file A string naming a directory or file respectively.
 #' @param all_info Whether to return names only, or all information in a directory listing.
-#' @param src, dest The source and destination filenames for uploading and downloading. Paths are allowed.
+#' @param src,dest The source and destination filenames for uploading and downloading. Paths are allowed.
 #' @param confirm Whether to ask for confirmation on deleting a file or directory.
 #'
 #' @return

R/storage_properties.R

@@ -1,3 +1,14 @@
+#' Get storage properties for an endpoint or container
+#'
+#' @param object An object.
+#' @param container A blob container.
+#' @param share A file share.
+#' @param blob,file,dir The name of an individual blob, file or directory.
+#'
+#' @details
+#' The `get_storage_properties` generic returns a list of properties for the given storage object. There are methods defined for objects of class `storage_endpoint`, `blob_container` and `file_share`. Similar functions are defined for individual blobs, files and directories.
+#'
+#' @rdname properties
 #' @export
 get_storage_properties <- function(object, ...)
 {
@@ -5,6 +16,7 @@ get_storage_properties <- function(object, ...)
 }
 
 
+#' @rdname properties
 #' @export
 get_storage_properties.storage_endpoint <- function(object)
 {
@@ -13,6 +25,7 @@ get_storage_properties.storage_endpoint <- function(object)
 }
 
 
+#' @rdname properties
 #' @export
 get_storage_properties.blob_container <- function(object)
 {
@@ -22,6 +35,7 @@ get_storage_properties.blob_container <- function(object)
 }
 
 
+#' @rdname properties
 #' @export
 get_storage_properties.file_share <- function(object)
 {
@@ -31,8 +45,9 @@ get_storage_properties.file_share <- function(object)
 }
 
 
+#' @rdname properties
 #' @export
-get_azure_blob_properties <- function(container, blob)
+get_blob_properties <- function(container, blob)
 {
     res <- do_container_op(container, blob, http_verb="HEAD", http_status_handler="pass")
     httr::stop_for_status(res, storage_error_message(res))
@@ -40,6 +55,7 @@ get_azure_blob_properties <- function(container, blob)
 }
 
 
+#' @rdname properties
 #' @export
 get_azure_file_properties <- function(share, file)
 {
@@ -49,6 +65,7 @@ get_azure_file_properties <- function(share, file)
 }
 
 
+#' @rdname properties
 #' @export
 get_azure_dir_properties <- function(share, dir)
 {

man/blob_container.Rd

@@ -18,7 +18,7 @@ delete_blob(container, blob, confirm = TRUE)
 \arguments{
 \item{container}{A blob container object.}
 
-\item{src, }{dest The source and destination filenames for uploading and downloading. Paths are allowed.}
+\item{src, dest}{The source and destination filenames for uploading and downloading. Paths are allowed.}
 
 \item{blob}{A string naming a blob.}
 

man/blob_endpoint.Rd

@@ -53,7 +53,7 @@ delete_blob_container(endpoint, ...)
 
 \item{...}{Further arguments passed to lower-level functions.}
 
-\item{key, }{sas If an endpoint object is not supplied, authentication details. If neither an access key nor a SAS are provided, only public (anonymous) access to the share is possible.}
+\item{key, sas}{If an endpoint object is not supplied, authentication details. If neither an access key nor a SAS are provided, only public (anonymous) access to the share is possible.}
 
 \item{api_version}{If an endpoint object is not supplied, the storage API version to use when interacting with the host. Currently defaults to \code{"2017-07-29"}.}
 

man/file_endpoint.Rd

@@ -51,7 +51,7 @@ delete_file_share(endpoint, ...)
 
 \item{...}{Further arguments passed to lower-level functions.}
 
-\item{key, }{sas If an endpoint object is not supplied, authentication details. If neither an access key nor a SAS are provided, only public (anonymous) access to the share is possible.}
+\item{key, sas}{If an endpoint object is not supplied, authentication details. If neither an access key nor a SAS are provided, only public (anonymous) access to the share is possible.}
 
 \item{api_version}{If an endpoint object is not supplied, the storage API version to use when interacting with the host. Currently defaults to \code{"2017-07-29"}.}
 

man/file_share.Rd

@@ -24,11 +24,11 @@ delete_azure_dir(share, dir, confirm = TRUE)
 \arguments{
 \item{share}{A file share object.}
 
-\item{dir, }{file A string naming a directory or file respectively.}
+\item{dir, file}{A string naming a directory or file respectively.}
 
 \item{all_info}{Whether to return names only, or all information in a directory listing.}
 
-\item{src, }{dest The source and destination filenames for uploading and downloading. Paths are allowed.}
+\item{src, dest}{The source and destination filenames for uploading and downloading. Paths are allowed.}
 
 \item{confirm}{Whether to ask for confirmation on deleting a file or directory.}
 }

man/file_transfer.Rd

@@ -10,7 +10,7 @@ download_from_url(src, dest, ..., overwrite = FALSE)
 upload_to_url(src, dest, ...)
 }
 \arguments{
-\item{src, }{dest The source and destination files/URLs. Paths are allowed.}
+\item{src, dest}{The source and destination files/URLs. Paths are allowed.}
 
 \item{...}{Further arguments to pass to lower-level functions. In particular, use \code{key} and/or \code{sas} to supply an access key or SAS. Without a key or SAS, only unauthenticated (anonymous) access is possible.}
 

man/lease.Rd

@@ -0,0 +1,47 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/blob_lease.R
+\name{acquire_lease}
+\alias{acquire_lease}
+\alias{break_lease}
+\alias{release_lease}
+\alias{renew_lease}
+\alias{change_lease}
+\title{Operations on blob leases}
+\usage{
+acquire_lease(container, blob = "", duration = 60, lease = NULL)
+
+break_lease(container, blob = "", period = NULL)
+
+release_lease(container, blob = "", lease)
+
+renew_lease(container, blob = "", lease)
+
+change_lease(container, blob = "", lease, new_lease)
+}
+\arguments{
+\item{container}{A blob container object.}
+
+\item{blob}{The name of an individual blob. If not supplied, the lease applies to the entire container.}
+
+\item{duration}{For \code{acquire_lease}, The duration of the requested lease. For an indefinite duration, set this to -1.}
+
+\item{lease}{For \code{acquire_lease} an optional proposed name of the lease; for \code{release_lease}, \code{renew_lease} and \code{change_lease}, the name of the existing lease.}
+
+\item{period}{For \code{break_lease}, the period for which to break the lease.}
+
+\item{new_lease}{For \code{change_lease}, the proposed name of the lease.}
+}
+\value{
+For \code{acquire_lease} and \code{change_lease}, a string containing the lease ID.
+}
+\description{
+Manage leases for blobs and blob containers.
+}
+\details{
+Leasing is a way to prevent a blob or container from being accidentally deleted. The duration of a lease can range from 15 to 60 seconds, or be indefinite.
+}
+\seealso{
+\link{blob_container},
+\href{https://docs.microsoft.com/en-us/rest/api/storageservices/lease-blob}{Leasing a blob},
+\href{https://docs.microsoft.com/en-us/rest/api/storageservices/lease-container}{Leasing a container}
+}

man/properties.Rd

@@ -0,0 +1,41 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/storage_properties.R
+\name{get_storage_properties}
+\alias{get_storage_properties}
+\alias{get_storage_properties.storage_endpoint}
+\alias{get_storage_properties.blob_container}
+\alias{get_storage_properties.file_share}
+\alias{get_blob_properties}
+\alias{get_azure_file_properties}
+\alias{get_azure_dir_properties}
+\title{Get storage properties for an endpoint or container}
+\usage{
+get_storage_properties(object, ...)
+
+\method{get_storage_properties}{storage_endpoint}(object)
+
+\method{get_storage_properties}{blob_container}(object)
+
+\method{get_storage_properties}{file_share}(object)
+
+get_blob_properties(container, blob)
+
+get_azure_file_properties(share, file)
+
+get_azure_dir_properties(share, dir)
+}
+\arguments{
+\item{object}{An object.}
+
+\item{container}{A blob container.}
+
+\item{blob, file, dir}{The name of an individual blob, file or directory.}
+
+\item{share}{A file share.}
+}
+\description{
+Get storage properties for an endpoint or container
+}
+\details{
+The \code{get_storage_properties} generic returns a list of properties for the given storage object. There are methods defined for objects of class \code{storage_endpoint}, \code{blob_container} and \code{file_share}. Similar functions are defined for individual blobs, files and directories.
+}