Update documentation (#112)

* Rework box-auth functions (fix #96):

- deprecate box_attach_on_auth()
- deprecate write.Renv arg to box_auth()
  - write environment variables to console instead
- refactor box_auth(), box_fresh_auth():
  - import glue and fs (both low depencency)

Also, fix typo in box_read() documentation

* Add deprecation to documentation, add is_void() to internal functions

* Update documentation for functions:

- box_auth()
- box_ls()
- box_setwd()
- box_dir_create()

* update docs

* Update docs

* Update function-documentation

* Complete first-pass through function-documentation

* clean up function-documentation

* Puts in placeholders for JWT authentication

* Split vignettes

* Update R/boxr_misc.R

Co-Authored-By: Nate <nathancday@gmail.com>

* Update R/boxr_read.R

Co-Authored-By: Nate <nathancday@gmail.com>

* Make S3 class-descriptions consistent

* remove author from function-docs, we will rely on package authorship for attribution

* - Deprecate filename, not file_name
- Harmonize punctuation

* Add `...` arg to box_source(), passed to source().

Update documentation for `source()`.

Harmonize other documentation.

* Clean up the deprecation of `filename` argument

* update hyperlinks to box.com, rebuild vignettes

* Go with a less-is-more approach, let the reader refer to the rio documentation if they wish.

* removed hanging backtick in box_read() and re-doc'd for changed roxygen front-matter

* Clean-up

.gitignore

@@ -10,3 +10,4 @@ packrat/lib*/
 tests/testthat/test_dir
 .httr-oauth
 .Rhistory
+inst/doc

NEWS.md

@@ -2,8 +2,13 @@
 
 ## Improvements
 
+* modifies `box_source()`: adds `...` argument to pass other arguments to `source()`.
+
+* modifies `box_write()`, `box_dl()`:
+  - deprecates the `filename` argument in favor of `file_name`.
+
 * modifies `box_auth()` (#96):
-  - deprecates `write.Renv` arigument
+  - deprecates `write.Renv` argument
   - copies text to the clipboard, rather than overwrite the `.Renviron` file
   - returns `invisible(NULL)` upon success 
 

R/boxr-package.R

@@ -1,28 +1,23 @@
 #' boxr: access the Box API
 #' 
-#' A light-weight, high-level R interface for the box.com API
+#' A lightweight, high-level R interface for the [box.com](https://developer.box.com/docs) API
 #' 
-#' An introduction to the package, and a short getting started guide (including 
-#' how to authorize boxr to work with your box.com account), can be found in the
-#' package's vignette. Simply run
+#' This package has a documentation-website (created using [pkgdown](https://pkgdown.r-lib.org/)), containing:
 #' 
-#' `vignette("boxr")`
+#' - [README](https://r-box.github.io/boxr)
+#' - [Get-started article](https://r-box.github.io/boxr/articles/boxr.html), 
+#'   also accessible from R: `vignette("boxr")`
+#' - [Function reference](https://r-box.github.io/boxr/reference/index.html)
 #' 
-#' and it should open in your browser.
+#' The `boxr` source-repository is at GitHub: <https://github.com/r-box/boxr>. 
 #' 
-#' To see a list of the functions which `boxr` provides, click on the 
-#' "Index" hyperlink at the bottom of this page.
-#' 
-#' `boxr`'s home on the internet is currently GitHub: 
-#' <https://github.com/r-box/boxr>. If you find anything you think might
-#' be a bug, do report it as a 
-#' \href{https://github.com/r-box/boxr/issues}{GitHub issue}!
+#' If you find anything you think might be a bug, please report it as a 
+#' [GitHub issue](https://github.com/r-box/boxr/issues)!
 #' 
 #' Happy hacking! :)
 #'
 #' @name boxr-package
 #' @aliases boxr
 #' @docType package
-#' @author Brendan Rocks \email{foss@@brendanrocks.com}
 #' @keywords package
 NULL

R/boxr__internal_diff_and_uldl.R

@@ -41,7 +41,7 @@ downloadDirFiles <- function(dir_id, local_dir = getwd(), overwrite = TRUE,
       ))
 
       downloads[[i]] <-
-        try(box_dl(to_dl$id[i], filename = names(to_dl$id[i]), overwrite = TRUE, 
+        try(box_dl(to_dl$id[i], file_name = names(to_dl$id[i]), overwrite = TRUE, 
                    local_dir = local_dir, pb = FALSE), silent = TRUE)
     }
 

R/boxr__internal_dir_comparison.R

@@ -117,8 +117,6 @@
 #' 
 #' @references
 #'   <https://developers.box.com/docs>
-#'   
-#' @author Brendan Rocks \email{foss@@brendanrocks.com}
 #' 
 #' @seealso [box_fetch()] and [box_push()], which depend on
 #'   this internal function, [file.info()] for timestamps describing

R/boxr__internal_update_upload.R

@@ -15,8 +15,8 @@
 #' @param file A path to a file stored locally
 #' @param dir_id The box.com id for the folder that you'd like to upload to
 #' @return The [httr()] object returned by the api call
-#' @author Brendan Rocks \email{foss@@brendanrocks.com}
 #' @keywords internal
+#' 
 box_upload_new <- function(dir_id, file, pb = FALSE) {
   httr::POST(
     "https://upload.box.com/api/2.0/files/content",

R/boxr_add_description.R

@@ -1,19 +1,17 @@
-#' Add description to a Box file
+#' Add description to Box file
 #' 
-#' Files hosted on box.com can have small descriptions underneath their
-#' filenames. This can be useful to explain the contents of the file, or even to
-#' leave 'git commit' style messages about the latest changes made to them.
+#' This function will attach a description to a Box file; it will
+#' overwrite the Box file's existing description.
+#' 
+#' Files hosted at Box can have small text-descriptions that 
+#' you can be use to annotate files, or even to
+#' leave 'git commit' style messages.
 #' 
-#' @md
 #' @inheritParams box_dl
-#' @param description The description which you'd like to add to the file. 
-#'   [character()].
-#'   
-#' @return An object of class [boxr_file_reference][boxr_S3_classes].
-#'
-#' @author Brendan Rocks \email{foss@@brendanrocks.com}
+#' @return Object with S3 class [`boxr_file_reference`][boxr_S3_classes].
 #' 
 #' @export
+#' 
 box_add_description <- function(file_id, description) {
   file_id <- handle_file_id(file_id)
 

R/boxr_auth.R

@@ -3,9 +3,10 @@
 #' @description
 #' `box_auth()` serves two purposes:
 #' 
-#' 1. connecting [box.com](https://box.com) accounts with **boxr** 
-#'    for the first time
-#' 2. connecting to previously-connected [box.com](https://box.com) accounts
+#' 1. connecting to [box.com](https://developer.box.com/docs) 
+#'    accounts from **boxr** for the first time
+#' 2. connecting to previously-connected 
+#'    [box.com](https://developer.box.com/docs) accounts
 #'
 #' In either case, it should be sufficient to run `box_auth()` with no
 #' parameters. If you have authenticated with boxr before, this should be all
@@ -18,7 +19,7 @@
 #' screenshots. To view the vignette, run `vignette("boxr")`, or visit this
 #' [article](https://r-box.github.io/boxr/articles/boxr.html). To use boxr
 #' for the first time, you need to enable API access for your 
-#' [box.com](https://box.com) account. The process is slightly annoying. 
+#' [box.com](https://developer.box.com/docs) account. The process is slightly annoying. 
 #' You only need to do it once - it takes around two minutes.
 #'
 #' The next time you use boxr, you should be able to just run
@@ -49,7 +50,7 @@
 #'     which might be shared with others.
 #'
 #' A browser window should open, for you to formally grant yourself access to
-#' your files at [box.com](https://box.com).
+#' your files at [box.com](https://developer.box.com/docs).
 #'
 #' From this point on, simply running `box_auth()` at the start of a
 #' session should be all that is required.
@@ -59,7 +60,7 @@
 #' This function has some side effects, which make subsequent calls to 
 #' `box_auth()` easier:
 #' 
-#' - a browser window may be opened at [box.com](https://box.com), 
+#' - a browser window may be opened at [box.com](https://developer.box.com/docs), 
 #'   for you to authorize to your Box app.
 #'  
 #' - a token file is written, according to the value of `cache`. The default
@@ -81,18 +82,16 @@
 #'   the client id for the account to use.
 #' @param client_secret `character`, 
 #'   the client secret for the account to use. 
-#' @param interactive `logical`, should the authorization process happen
-#'   interactively (requiring user input to the R console, and/or a visit to
-#'   [box.com](https://box.com))?
-#' @param write.Renv **deprecated**
-#' @param ... other arguments passed to [httr::oauth2.0_token()]
+#' @param interactive `logical`, indicates that the authorization process 
+#'   will be interactive (requiring user input to the R console, and/or a 
+#'   visit to [box.com](https://developer.box.com/docs)).
+#' @param write.Renv **deprecated**.
+#' @param ... Other arguments passed to [httr::oauth2.0_token()].
 #'
-#' @return `invisible(NULL)`, called for side-effects
+#' @return `invisible(NULL)`, called for side-effects.
 #'
 #' See [httr::oauth2.0_token()] for details.
 #'
-#' @author Brendan Rocks \email{foss@@brendanrocks.com}
-#'
 #' @seealso [httr::oauth2.0_token()] for details on how tokens are handled
 #'
 #' @export
@@ -288,7 +287,7 @@ box_auth <- function(client_id = NULL, client_secret = NULL,
 #' is often the solution to authorisation problems.
 #'
 #' @inheritParams box_auth
-#' @param ... other args passed to [box_auth()]
+#' @param ... Other arguments passed to [box_auth()].
 #' 
 #' @seealso [box_auth()] for the usual method of authorisation
 #'   
@@ -326,16 +325,15 @@ box_fresh_auth <- function(cache = "~/.boxr-oauth", ...) {
 #'   * You use more than one box.com account. Things could get
 #'   rather confusing.
 #'
-#' @param auth_on_attach Should boxr try and connect to your account when
-#' attached? `logical`
-#'
-#' @return Nothing; invoked for it's side effect.
+#' @param auth_on_attach `logical`, indicates if boxr should authenticate 
+#'   as soon as it's loaded.
 #'
-#' @author Brendan Rocks \email{foss@@brendanrocks.com}
+#' @return `invisible(NULL)`, called for side-effects.
 #'
 #' @seealso [box_auth()]
 #'
 #' @export
+#' 
 box_auth_on_attach <- function(auth_on_attach = FALSE) {
   assertthat::assert_that(!is.na(auth_on_attach))
   assertthat::assert_that(is.logical(auth_on_attach))
@@ -384,5 +382,7 @@ box_auth_on_attach <- function(auth_on_attach = FALSE) {
       "'attached', e.g.    \nlibrary(boxr)\n"
     )
   }
+
+  invisible(NULL)
 }
 

R/boxr_delete_restore.R

@@ -1,86 +1,84 @@
 #' Move files within Box, from/to trash directory
 #' 
-#' @description 
-#' * `box_delete_file` moves a file to the trash folder.
-#' * `box_delete_folder` moves a whole folder (and all of it's 
-#'     contents) to the trash folder.
-#' * `box_restore_file` moves a file from the trash, to wherever it 
-#'     was before
-#' * `box_delete_folder` does the same thing for a folder.
+#' In the Box context, deleting a file moves it to a special folder
+#' within your Box account: 'Trash'. As of mid-2019, Box' default
+#' [policy](https://community.box.com/t5/Managing-Files-and-Folders/Manage-Trash/ta-p/19212)
+#' is to retain files in Trash for 30 days.
+#'
+#' \describe{
+#'   \item{`box_delete_file()`}{Move a file to Trash.}
+#'   \item{`box_restore_file()`}{Restore a file from Trash.}
+#'   \item{`box_delete_folder()`}{Move a folder, including contents, to Trash.}
+#'   \item{`box_restore_folder()`}{Restore a folder, including contents, from Trash.}
+#' }
 #' 
 #' @aliases box_delete_folder box_restore_file box_delete_folder
-#' @param file_id The box.com id for the file that you'd like delete/restore
-#' @param dir_id The box.com id for the folder that you'd like delete/restore 
 #' 
-#' @details 'Deleting' a file in this case means moving it to a special folder
-#'   within your box.com account called the 'Trash'. At the time of writing,
-#'   the files are stored for three months before being deleted, and the 
-#'   contents of the folder can be accessed from the top right hand menu of the 
-#'   web interface.
-#' 
-#' @return An object of class [boxr_file_reference][boxr_S3_classes].
-#' 
-#' @author Brendan Rocks \email{foss@@brendanrocks.com}
-#' 
-#' @seealso [box_ul()], for putting files there in the first place
+#' @inheritParams box_setwd
+#' @inheritParams box_dl 
+#' @return \describe{
+#'   \item{`box_delete_file()`}{Object with S3 class [`boxr_file_reference`][boxr_S3_classes].}
+#'   \item{`box_restore_file()`}{Object with S3 class [`boxr_file_reference`][boxr_S3_classes].}
+#'   \item{`box_delete_folder()`}{Object with S3 class [`boxr_folder_reference`][boxr_S3_classes].}
+#'   \item{`box_restore_folder()`}{Object with S3 class [`boxr_folder_reference`][boxr_S3_classes].}
+#' }
 #' 
 #' @export
 box_delete_file <- function(file_id) {
   add_file_ref_class(httr::content(boxDeleteFile(file_id)))
 }
 
-
 #' @rdname box_delete_file
 #' @export
-box_delete_folder <- function(dir_id) {
-  add_folder_ref_class(httr::content(boxDeleteFolder(dir_id)))
-}
-
-
-#' @rdname box_delete_file
-#' @export
-box_restore_folder <- function(dir_id) {
+box_restore_file <- function(file_id) {
   req <- httr::POST(
     paste0(
-      "https://api.box.com/2.0/folders/",
-      dir_id
+      "https://api.box.com/2.0/file/",
+      file_id
     ),
     httr::config(token = getOption("boxr.token"))
   )
 
   if (httr::http_status(req)$message == "Success: (201) Created")
-    catif(paste0("dir id ", dir_id, " sucessfully restored from trash."))
+    catif(paste0("file id ", file_id, " sucessfully restored from trash."))
 
   # You could add something here to try and anticipate what happened;
   # the messages from box aren't terribly informative.
   # e.g. you get a 403 if the folder already exists, which you really shouldn't
   httr::stop_for_status(req)
-  add_folder_ref_class(httr::content(req))
+  add_file_ref_class(httr::content(req))
+}
+
+#' @rdname box_delete_file
+#' @export
+box_delete_folder <- function(dir_id) {
+  add_folder_ref_class(httr::content(boxDeleteFolder(dir_id)))
 }
 
 
 #' @rdname box_delete_file
 #' @export
-box_restore_file <- function(file_id) {
+box_restore_folder <- function(dir_id) {
   req <- httr::POST(
     paste0(
-      "https://api.box.com/2.0/file/",
-      file_id
+      "https://api.box.com/2.0/folders/",
+      dir_id
     ),
     httr::config(token = getOption("boxr.token"))
   )
 
   if (httr::http_status(req)$message == "Success: (201) Created")
-    catif(paste0("file id ", file_id, " sucessfully restored from trash."))
+    catif(paste0("dir id ", dir_id, " sucessfully restored from trash."))
 
   # You could add something here to try and anticipate what happened;
   # the messages from box aren't terribly informative.
   # e.g. you get a 403 if the folder already exists, which you really shouldn't
   httr::stop_for_status(req)
-  add_file_ref_class(httr::content(req))
+  add_folder_ref_class(httr::content(req))
 }
 
 
+
 # Internal versions -------------------------------------------------------
 # The following are internal versions, needed to return additional information
 # used by the dir-wide ops (e.g. deleteRemoteObjects used by box_push), not