Finishi respond to CRAN comments

See cran-comments.md for more detail.

- Give all functions \values
- Boost up examples a bit

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

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

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

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

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,

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

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", ...) {

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.
 #'

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, ...) {

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)
 #' }
 #'

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

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
 #'

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 = "[email protected]")
 #' }
 rt_user_create <- function(name,
                            password = NULL,

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

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, ...) {

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
+> <http:...> or <https:...>
+> 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: