From efa5acf57e99c60d2475fc8d200c907198f404f5 Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Mon, 12 Feb 2024 17:02:41 -0800 Subject: [PATCH] Fiddle with usage and params of `use_course_details` topic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is an internal piece of documentation, but is generating a NOTE on r-devel. It looks like this: Documented arguments not in \usage in Rd file 'use_course_details.Rd': ‘destdir’ ‘zipfile’ Functions with \usage entries need to have the appropriate \alias entries, and all their arguments documented. The \usage entries must correspond to syntactically valid R code. See chapter ‘Writing R documentation files’ in the ‘Writing R Extensions’ manual. --- R/course.R | 40 +++++++++++++++++++-------------------- man/use_course_details.Rd | 28 ++++++++++++++++----------- 2 files changed, 37 insertions(+), 31 deletions(-) diff --git a/R/course.R b/R/course.R index 53b7e4d7b..26dc70614 100644 --- a/R/course.R +++ b/R/course.R @@ -105,16 +105,31 @@ use_zip <- function(url, #' #' @name use_course_details #' @keywords internal +#' @usage +#' tidy_download(url, destdir = getwd()) +#' tidy_unzip(zipfile, cleanup = FALSE) #' + +#' @param url A GitHub, DropBox, or Google Drive URL. +#' * For `create_download_url()`: A URL copied from a web browser. +#' * For `tidy_download()`: A download link for a ZIP file, possibly behind a +#' shortlink or other redirect. `create_download_url()` can be helpful for +#' creating this URL from typical browser URLs. +#' @param destdir Path to existing local directory where the ZIP file will be +#' stored. Defaults to current working directory, but note that [use_course()] +#' has different default behavior. +#' @param zipfile Path to local ZIP file. +#' @param cleanup Whether to delete the ZIP file after unpacking. In an +#' interactive session, `cleanup = NA` leads to asking the user if they +#' want to delete or keep the ZIP file. + #' @section tidy_download(): #' #' ``` -#' ## function signature -#' tidy_download(url, destdir = getwd()) -#' -#' # as called inside use_course() +#' # how it's used inside use_course() #' tidy_download( -#' url, ## after post-processing with normalize_url() +#' # url has been processed with internal helper normalize_url() +#' url, #' # conspicuous_place() = `getOption('usethis.destdir')` or desktop or home #' # directory or working directory #' destdir = destdir %||% conspicuous_place() @@ -198,17 +213,6 @@ use_zip <- function(url, #' #' Use `create_download_url()` to perform this transformation automatically. #' -#' @param url Download link for the ZIP file, possibly behind a shortlink or -#' other redirect. See Details. -#' @param destdir Path to existing local directory where the ZIP file will be -#' stored. Defaults to current working directory, but note that [use_course()] -#' has different default behavior. -#' -#' @examples -#' \dontrun{ -#' tidy_download("https://github.com/r-lib/rematch2/archive/main.zip") -#' } -#' #' @section tidy_unzip(): #' #' Special-purpose function to unpack a ZIP file and (attempt to) create the @@ -234,8 +238,6 @@ use_zip <- function(url, #' hidden files, such as `.RData`, `.Rhistory`, and those below `.git/` and #' `.Rproj.user`. #' -#' @param zipfile Path to local ZIP file. -#' #' @examples #' \dontrun{ #' tidy_download("https://github.com/r-lib/rematch2/archive/main.zip") @@ -395,8 +397,6 @@ tidy_unzip <- function(zipfile, cleanup = FALSE) { } #' @rdname use_course_details -#' @param url a GitHub, DropBox, or Google Drive URL, as copied from a web -#' browser. #' @examples #' # GitHub #' create_download_url("https://github.com/r-lib/usethis") diff --git a/man/use_course_details.Rd b/man/use_course_details.Rd index c231cebf9..bef017345 100644 --- a/man/use_course_details.Rd +++ b/man/use_course_details.Rd @@ -5,17 +5,29 @@ \alias{create_download_url} \title{Helpers to download and unpack a ZIP file} \usage{ +tidy_download(url, destdir = getwd()) +tidy_unzip(zipfile, cleanup = FALSE) + create_download_url(url) } \arguments{ -\item{url}{a GitHub, DropBox, or Google Drive URL, as copied from a web -browser.} +\item{url}{A GitHub, DropBox, or Google Drive URL. +\itemize{ +\item For \code{create_download_url()}: A URL copied from a web browser. +\item For \code{tidy_download()}: A download link for a ZIP file, possibly behind a +shortlink or other redirect. \code{create_download_url()} can be helpful for +creating this URL from typical browser URLs. +}} \item{destdir}{Path to existing local directory where the ZIP file will be stored. Defaults to current working directory, but note that \code{\link[=use_course]{use_course()}} has different default behavior.} \item{zipfile}{Path to local ZIP file.} + +\item{cleanup}{Whether to delete the ZIP file after unpacking. In an +interactive session, \code{cleanup = NA} leads to asking the user if they +want to delete or keep the ZIP file.} } \description{ Details on the internal and helper functions that power \code{\link[=use_course]{use_course()}} and @@ -24,12 +36,10 @@ Details on the internal and helper functions that power \code{\link[=use_course] \section{tidy_download()}{ -\if{html}{\out{
}}\preformatted{## function signature -tidy_download(url, destdir = getwd()) - -# as called inside use_course() +\if{html}{\out{
}}\preformatted{# how it's used inside use_course() tidy_download( - url, ## after post-processing with normalize_url() + # url has been processed with internal helper normalize_url() + url, # conspicuous_place() = `getOption('usethis.destdir')` or desktop or home # directory or working directory destdir = destdir \%||\% conspicuous_place() @@ -149,10 +159,6 @@ hidden files, such as \code{.RData}, \code{.Rhistory}, and those below \verb{.gi } \examples{ -\dontrun{ -tidy_download("https://github.com/r-lib/rematch2/archive/main.zip") -} - \dontrun{ tidy_download("https://github.com/r-lib/rematch2/archive/main.zip") tidy_unzip("rematch2-main.zip")