From bfc8fe8fa07ec88e258e7472101480d408bb3842 Mon Sep 17 00:00:00 2001 From: Bryce Mecum Date: Tue, 21 Apr 2020 21:24:01 -0800 Subject: [PATCH] Finishi respond to CRAN comments See cran-comments.md for more detail. - Give all functions \values - Boost up examples a bit --- DESCRIPTION | 2 +- R/rt_login.R | 1 + R/rt_logout.R | 1 + R/rt_queue_properties.R | 2 ++ R/rt_ticket_attachment.R | 9 ++++- R/rt_ticket_attachment_content.R | 3 +- R/rt_ticket_history.R | 6 ++-- R/rt_ticket_history_reply.R | 1 + R/rt_ticket_links.R | 3 ++ R/rt_ticket_links_edit.R | 3 +- R/rt_ticket_properties.R | 1 + R/rt_ticket_search.R | 4 +-- R/rt_user_create.R | 4 +++ R/rt_user_edit.R | 1 + R/rt_user_properties.R | 2 ++ cran-comments.md | 51 +++++++++++++++++++++++++++++ man/rt_login.Rd | 3 ++ man/rt_queue_properties.Rd | 3 ++ man/rt_ticket_attachment.Rd | 10 +++++- man/rt_ticket_attachment_content.Rd | 2 +- man/rt_ticket_history.Rd | 7 ++-- man/rt_ticket_history_reply.Rd | 1 + man/rt_ticket_links.Rd | 4 +++ man/rt_ticket_links_edit.Rd | 3 +- man/rt_ticket_properties.Rd | 3 ++ man/rt_ticket_search.Rd | 4 +-- man/rt_user_create.Rd | 4 +++ man/rt_user_properties.Rd | 4 +++ 28 files changed, 127 insertions(+), 15 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 24a1e4f..d7f9a91 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -24,7 +24,7 @@ Suggests: askpass, testthat, tibble Roxygen: list(markdown = TRUE) -RoxygenNote: 7.0.2 +RoxygenNote: 7.1.0 VignetteBuilder: knitr Encoding: UTF-8 LazyData: true diff --git a/R/rt_login.R b/R/rt_login.R index 82b6b12..a27573f 100644 --- a/R/rt_login.R +++ b/R/rt_login.R @@ -11,6 +11,7 @@ #' @param password (character) Your password. #' @param ... Other arguments passed to \code{\link{rt_POST}} #' +#' @return Either `TRUE`, invisibly, if logged in, or throws an error. #' @export #' #' @examples diff --git a/R/rt_logout.R b/R/rt_logout.R index e2c939c..65e7e84 100644 --- a/R/rt_logout.R +++ b/R/rt_logout.R @@ -4,6 +4,7 @@ #' Note: restarting your R session will also log you out. #' #' @param ... Other arguments passed to \code{\link{rt_POST}} +# #' @return (rt_api) The parsed response from RT #' #' @export diff --git a/R/rt_queue_properties.R b/R/rt_queue_properties.R index c85bc0e..d300eee 100644 --- a/R/rt_queue_properties.R +++ b/R/rt_queue_properties.R @@ -3,6 +3,8 @@ #' @param queue (character) The queue #' @param ... Other arguments passed to \code{\link{rt_GET}} #' +#' @return (list) A list of queue properties +#' #' @export #' #' @examples diff --git a/R/rt_ticket_attachment.R b/R/rt_ticket_attachment.R index 67e529d..42ee29e 100644 --- a/R/rt_ticket_attachment.R +++ b/R/rt_ticket_attachment.R @@ -7,11 +7,18 @@ #' @param attachment_id (numeric) The attachment identifier #' @param ... Other arguments passed to \code{\link{rt_GET}} #' +#' @return (rt_api) An `rt_api` object with the response +#' #' @export #' #' @examples #' \dontrun{ -#' rt_ticket_attachment(2, 1) +#' # Before running rt_ticket_attachment, you'll probably want to get a list of +#' # the attachments for a given ticket, like: +#' attachments <- rt_ticket_attachments(1) # Ticket ID 1 +#' +#' # And then you can get information about a specific attachment: +#' rt_ticket_attachment(1, 3) # Attachment 3 on ticket 1 #' } rt_ticket_attachment <- function(ticket_id, attachment_id, diff --git a/R/rt_ticket_attachment_content.R b/R/rt_ticket_attachment_content.R index f36c17a..3e44a83 100644 --- a/R/rt_ticket_attachment_content.R +++ b/R/rt_ticket_attachment_content.R @@ -8,7 +8,8 @@ #' @inheritParams rt_ticket_attachment #' @param ... Other arguments passed to \code{\link{rt_GET}} #' -#' @return (response) A `response` object with the response +#' @return (rt_api) An `rt_api` object with the response +#' #' @export #' #' @examples diff --git a/R/rt_ticket_history.R b/R/rt_ticket_history.R index 4ea1974..b5eab00 100644 --- a/R/rt_ticket_history.R +++ b/R/rt_ticket_history.R @@ -6,14 +6,16 @@ #' Defaults to \code{l}. #' @param ... Other arguments passed to \code{\link{rt_GET}} #' +#' @return (rt_api) An `rt_api` object with the response +#' #' @export #' #' @examples #' \dontrun{ -#' # Get the full ticket history +#' # Get the full ticket history for ticket 992 #' rt_ticket_history(992) #' -#' # Get just the ticket ID and subject +#' # Get just the ticket ID and subject for ticket 992 #' rt_ticket_history(992, format = "s") #' } rt_ticket_history <- function(ticket_id, format = "l", ...) { diff --git a/R/rt_ticket_history_reply.R b/R/rt_ticket_history_reply.R index 5308c40..71a06d2 100644 --- a/R/rt_ticket_history_reply.R +++ b/R/rt_ticket_history_reply.R @@ -14,6 +14,7 @@ #' #' @examples #' \dontrun{ +#' # Reply to ticket 11 with a courteous message #' rt_ticket_history_reply(11, #' "Thank you. #' diff --git a/R/rt_ticket_links.R b/R/rt_ticket_links.R index ff6edad..4ea2549 100644 --- a/R/rt_ticket_links.R +++ b/R/rt_ticket_links.R @@ -8,10 +8,13 @@ #' @inheritParams rt_ticket_attachment #' @param ... Other arguments passed to \code{\link{rt_GET}} #' +#' @return (rt_api) An `rt_api` object with the response +#' #' @export #' #' @examples #' \dontrun{ +#' # Assuming have a ticket with id 1007, we can get it links by calling #' rt_ticket_links(1007) #' } rt_ticket_links <- function(ticket_id, ...) { diff --git a/R/rt_ticket_links_edit.R b/R/rt_ticket_links_edit.R index 8db6bda..0b79510 100644 --- a/R/rt_ticket_links_edit.R +++ b/R/rt_ticket_links_edit.R @@ -14,7 +14,8 @@ #' #' @examples #' \dontrun{ -#' # Make ticket 20 depend on ticket 21 +#' # Assuming we have tickets 20 and 21, we can make ticket 20 depend on ticket +#' # 21 #' rt_ticket_links_edit(20, depends_on = 21) #' } #' diff --git a/R/rt_ticket_properties.R b/R/rt_ticket_properties.R index c319e9b..07e2ed1 100644 --- a/R/rt_ticket_properties.R +++ b/R/rt_ticket_properties.R @@ -5,6 +5,7 @@ #' @inheritParams rt_ticket_attachment #' @param ... Other arguments passed to \code{\link{rt_GET}} #' +#' @return (list) A list of the ticket's properties #' @export #' #' @examples diff --git a/R/rt_ticket_search.R b/R/rt_ticket_search.R index e1af2e4..c6573b6 100644 --- a/R/rt_ticket_search.R +++ b/R/rt_ticket_search.R @@ -68,8 +68,8 @@ tidy_long_search_result <- function(result) { #' results. #' @param ... Other arguments passed to \code{\link{rt_GET}} #' -#' @return Either a data.frame/tibble (when format is `l` or `s`) or a numeric -#' vector when its `i`. +#' @return Either a `data.frame` or `tibble` (when format is `l` or `s`) or a +#' numeric vector when it's `i`. #' #' @export #' diff --git a/R/rt_user_create.R b/R/rt_user_create.R index c93edbe..9ec166a 100644 --- a/R/rt_user_create.R +++ b/R/rt_user_create.R @@ -29,7 +29,11 @@ parse_user_create_body <- function(body) { #' #' @examples #' \dontrun{ +#' # Create a barebones user with just a name #' rt_user_create("Some Person") +#' +#' # Create user that also has an email address +#' rt_user_create("Person", email_address = "person@example.com") #' } rt_user_create <- function(name, password = NULL, diff --git a/R/rt_user_edit.R b/R/rt_user_edit.R index 7de0d0d..2fe7934 100644 --- a/R/rt_user_edit.R +++ b/R/rt_user_edit.R @@ -23,6 +23,7 @@ warn_user_edit_warnings <- function(body) { #' @param ... Other arguments passed to \code{\link{rt_POST}} #' #' @return The ID of the edited user +#' #' @export #' #' @examples diff --git a/R/rt_user_properties.R b/R/rt_user_properties.R index 9e0b597..ed78a79 100644 --- a/R/rt_user_properties.R +++ b/R/rt_user_properties.R @@ -3,10 +3,12 @@ #' @param user_id (numeric) The ID of the User to edit #' @param ... Other arguments passed to \code{\link{rt_GET}} #' +#' @return (list) A list of the user's properties #' @export #' #' @examples #' \dontrun{ +#' # Assuming we have a user with id 1, we can get its properties #' rt_user_properties(1) #' } rt_user_properties <- function(user_id, ...) { diff --git a/cran-comments.md b/cran-comments.md index 6ce9cc1..ba79b57 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,3 +1,54 @@ +## Resubmission + +This is a resubmission after comments from CRAN via email sent on April 3, 2020. +I have copied CRAN's comments here, placed in blockquote markup and provided my +response immediately following. + +CRAN wrote: + +> Please add a web reference for this API in your Description field of the +> DESCRIPTION file in the form +> or +> with angle brackets for auto-linking and no space after 'http:' and +> 'https:'. + +I have made this change. + +CRAN wrote: + +> Please always write non-English usage, package names, software names and +> API names in *undirected* single quotes in title and description in the +> DESCRIPTION file. + +I have single-quoted references to proper names in the `DESCRIPTION` file's +'Description' field as requested. + +CRAN wrote: + +> Please always add all authors, contibutors and copyright holders in the +> Authors@R field with the appropriate roles...[elided] + +I added my indicated copyright holder to the `DESCRIPTION` file with the role +`cph`. + +CRAN wrote: + +> When creating examples please keep in mind that the structure +> would be desirable: [elided] + +I appreciate the feedback on the style used in the examples. I have looked over +the examples in the exported functions and made some changes but I don't think +they quite match what you're looking for. I prefer my style over yours and would +like to keep the examples the way they are if at all possible. + +CRAN wrote: + +> Please add \value to all .Rd files for exported functions and explain +the functions results in the documentation. + +I have ensured all exported functions have `\value` tags in their associated +`.Rd` files. + ## Test environments On GitHub Actions: diff --git a/man/rt_login.Rd b/man/rt_login.Rd index 058e5ef..cf2dc3d 100644 --- a/man/rt_login.Rd +++ b/man/rt_login.Rd @@ -17,6 +17,9 @@ rt_login( \item{...}{Other arguments passed to \code{\link{rt_POST}}} } +\value{ +Either \code{TRUE}, invisibly, if logged in, or throws an error. +} \description{ Use this to log into RT at the start of your session. Once you call this function and successfully log in, calls of other functions within this diff --git a/man/rt_queue_properties.Rd b/man/rt_queue_properties.Rd index 0a5c134..2e29e01 100644 --- a/man/rt_queue_properties.Rd +++ b/man/rt_queue_properties.Rd @@ -11,6 +11,9 @@ rt_queue_properties(queue, ...) \item{...}{Other arguments passed to \code{\link{rt_GET}}} } +\value{ +(list) A list of queue properties +} \description{ Get the properties of a queue } diff --git a/man/rt_ticket_attachment.Rd b/man/rt_ticket_attachment.Rd index 9b1204c..d68675c 100644 --- a/man/rt_ticket_attachment.Rd +++ b/man/rt_ticket_attachment.Rd @@ -13,12 +13,20 @@ rt_ticket_attachment(ticket_id, attachment_id, ...) \item{...}{Other arguments passed to \code{\link{rt_GET}}} } +\value{ +(rt_api) An \code{rt_api} object with the response +} \description{ Retrieves attachment metadata. To get the attachment itself, see \link{rt_ticket_attachment_content}. } \examples{ \dontrun{ -rt_ticket_attachment(2, 1) +# Before running rt_ticket_attachment, you'll probably want to get a list of +# the attachments for a given ticket, like: +attachments <- rt_ticket_attachments(1) # Ticket ID 1 + +# And then you can get information about a specific attachment: +rt_ticket_attachment(1, 3) # Attachment 3 on ticket 1 } } diff --git a/man/rt_ticket_attachment_content.Rd b/man/rt_ticket_attachment_content.Rd index 63f5c28..8a76baf 100644 --- a/man/rt_ticket_attachment_content.Rd +++ b/man/rt_ticket_attachment_content.Rd @@ -14,7 +14,7 @@ rt_ticket_attachment_content(ticket_id, attachment_id, ...) \item{...}{Other arguments passed to \code{\link{rt_GET}}} } \value{ -(response) A \code{response} object with the response +(rt_api) An \code{rt_api} object with the response } \description{ Gets the content of the specified attachment for further processing or diff --git a/man/rt_ticket_history.Rd b/man/rt_ticket_history.Rd index 92bc73d..af9d998 100644 --- a/man/rt_ticket_history.Rd +++ b/man/rt_ticket_history.Rd @@ -15,15 +15,18 @@ Defaults to \code{l}.} \item{...}{Other arguments passed to \code{\link{rt_GET}}} } +\value{ +(rt_api) An \code{rt_api} object with the response +} \description{ Get a ticket's history } \examples{ \dontrun{ -# Get the full ticket history +# Get the full ticket history for ticket 992 rt_ticket_history(992) -# Get just the ticket ID and subject +# Get just the ticket ID and subject for ticket 992 rt_ticket_history(992, format = "s") } } diff --git a/man/rt_ticket_history_reply.Rd b/man/rt_ticket_history_reply.Rd index fe82997..f73b55c 100644 --- a/man/rt_ticket_history_reply.Rd +++ b/man/rt_ticket_history_reply.Rd @@ -37,6 +37,7 @@ Reply to a ticket } \examples{ \dontrun{ +# Reply to ticket 11 with a courteous message rt_ticket_history_reply(11, "Thank you. diff --git a/man/rt_ticket_links.Rd b/man/rt_ticket_links.Rd index e4c5655..2b42a51 100644 --- a/man/rt_ticket_links.Rd +++ b/man/rt_ticket_links.Rd @@ -11,6 +11,9 @@ rt_ticket_links(ticket_id, ...) \item{...}{Other arguments passed to \code{\link{rt_GET}}} } +\value{ +(rt_api) An \code{rt_api} object with the response +} \description{ Gets the ticket links for a single ticket. If applicable, the following fields will be returned: \code{HasMember}, @@ -19,6 +22,7 @@ and \code{DependsOn}. } \examples{ \dontrun{ +# Assuming have a ticket with id 1007, we can get it links by calling rt_ticket_links(1007) } } diff --git a/man/rt_ticket_links_edit.Rd b/man/rt_ticket_links_edit.Rd index 537d81d..51d6835 100644 --- a/man/rt_ticket_links_edit.Rd +++ b/man/rt_ticket_links_edit.Rd @@ -37,7 +37,8 @@ Edit the links on a ticket } \examples{ \dontrun{ -# Make ticket 20 depend on ticket 21 +# Assuming we have tickets 20 and 21, we can make ticket 20 depend on ticket +# 21 rt_ticket_links_edit(20, depends_on = 21) } diff --git a/man/rt_ticket_properties.Rd b/man/rt_ticket_properties.Rd index e9e1df4..c917c24 100644 --- a/man/rt_ticket_properties.Rd +++ b/man/rt_ticket_properties.Rd @@ -11,6 +11,9 @@ rt_ticket_properties(ticket_id, ...) \item{...}{Other arguments passed to \code{\link{rt_GET}}} } +\value{ +(list) A list of the ticket's properties +} \description{ Retrieves ticket properties } diff --git a/man/rt_ticket_search.Rd b/man/rt_ticket_search.Rd index 7143dc5..7b861b9 100644 --- a/man/rt_ticket_search.Rd +++ b/man/rt_ticket_search.Rd @@ -22,8 +22,8 @@ results.} \item{...}{Other arguments passed to \code{\link{rt_GET}}} } \value{ -Either a data.frame/tibble (when format is \code{l} or \code{s}) or a numeric -vector when its \code{i}. +Either a \code{data.frame} or \code{tibble} (when format is \code{l} or \code{s}) or a +numeric vector when it's \code{i}. } \description{ Search RT for tickets using RT's query syntax which is documented at diff --git a/man/rt_user_create.Rd b/man/rt_user_create.Rd index 74fcba2..f9fa5d3 100644 --- a/man/rt_user_create.Rd +++ b/man/rt_user_create.Rd @@ -40,6 +40,10 @@ Create a user } \examples{ \dontrun{ +# Create a barebones user with just a name rt_user_create("Some Person") + +# Create user that also has an email address +rt_user_create("Person", email_address = "person@example.com") } } diff --git a/man/rt_user_properties.Rd b/man/rt_user_properties.Rd index b8f716e..9135639 100644 --- a/man/rt_user_properties.Rd +++ b/man/rt_user_properties.Rd @@ -11,11 +11,15 @@ rt_user_properties(user_id, ...) \item{...}{Other arguments passed to \code{\link{rt_GET}}} } +\value{ +(list) A list of the user's properties +} \description{ Get a user's properties } \examples{ \dontrun{ +# Assuming we have a user with id 1, we can get its properties rt_user_properties(1) } }