Add docstrings to R Client (deephaven#4363)

* Add docstrings - .Rd not generated

* Snake case in docs PR

* Apply agg_all_by changes to docs

* Update docs to be more like Python

* Do not import all of dplyr and arrow

* Remove RecordBatchStreamReader directive

* Review suggestions

* Should be up-to-date with main

* Review sugestions

* Update client_wrapper.R

Co-authored-by: Chip Kent <5250374+chipkent@users.noreply.github.com>

* Update client_wrapper.R

Co-authored-by: Chip Kent <5250374+chipkent@users.noreply.github.com>

* Update client_wrapper.R

Co-authored-by: Chip Kent <5250374+chipkent@users.noreply.github.com>

* Update client_wrapper.R

Co-authored-by: Chip Kent <5250374+chipkent@users.noreply.github.com>

* Update client_wrapper.R

Co-authored-by: Chip Kent <5250374+chipkent@users.noreply.github.com>

* Update docs according to review

---------

Co-authored-by: Chip Kent <5250374+chipkent@users.noreply.github.com>

R/rdeephaven/NAMESPACE

@@ -7,7 +7,6 @@ S3method(as_tibble,TableHandle)
 S3method(dim,TableHandle)
 S3method(head,TableHandle)
 S3method(tail,TableHandle)
-export(Aggregation)
 export(Client)
 export(TableHandle)
 export(agg_abs_sum)
@@ -33,4 +32,4 @@ importFrom(arrow,as_arrow_table)
 importFrom(arrow,as_record_batch_reader)
 importFrom(dplyr,as_data_frame)
 importFrom(dplyr,as_tibble)
-useDynLib(rdeephaven, .registration = TRUE)
+useDynLib(rdeephaven, .registration = TRUE)

R/rdeephaven/R/aggregate_wrapper.R

@@ -1,3 +1,6 @@
+#' @description
+#' An Aggregation represents an aggregation operation that can be passed to `agg_by()` or `agg_all_by()`.
+#' Note that Aggregations should not be instantiated directly by user code, but rather by provided agg_* functions.
 Aggregation <- R6Class("Aggregation",
   cloneable = FALSE,
   public = list(
@@ -17,68 +20,148 @@ Aggregation <- R6Class("Aggregation",
 
 ### All of the functions below return an instance of the above class
 
+#' @description
+#' Creates a First aggregation that computes the first value of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_first <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_first, "agg_first", cols=cols))
 }
 
+#' @description
+#' Creates a Last aggregation that computes the last value of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_last <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_last, "agg_last", cols=cols))
 }
 
+#' @description
+#' Creates a Minimum aggregation that computes the minimum of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_min <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_min, "agg_min", cols=cols))
 }
 
+#' @description
+#' Creates a Maximum aggregation that computes the maximum of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_max <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_max, "agg_max", cols=cols))
 }
 
+#' @description
+#' Creates a Sum aggregation that computes the sum of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_sum <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_sum, "agg_sum", cols=cols))
 }
 
+#' @description
+#' Creates an Absolute Sum aggregation that computes the absolute sum of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_abs_sum <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_abs_sum, "agg_abs_sum", cols=cols))
 }
 
+#' @description
+#' Creates an Average aggregation that computes the average of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_avg <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_avg, "agg_avg", cols=cols))
 }
 
+#' @description
+#' Creates a Weighted Average aggregation that computes the weighted average of each column in `cols` for each aggregation group.
+#' @param wcol String denoting the column to use for weights. This must be a numeric column.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_w_avg <- function(wcol, cols = character()) {
   verify_string("wcol", wcol, TRUE)
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_w_avg, "agg_w_avg", wcol=wcol, cols=cols))
 }
 
+#' @description
+#' Creates a Median aggregation that computes the median of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_median <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_median, "agg_median", cols=cols))
 }
 
+#' @description
+#' Creates a Variance aggregation that computes the variance of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_var <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_var, "agg_var", cols=cols))
 }
 
+#' @description
+#' Creates a Standard Deviation aggregation that computes the standard deviation of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_std <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_std, "agg_std", cols=cols))
 }
 
+#' @description
+#' Creates a Percentile aggregation that computes the given percentile of each column in `cols` for each aggregation group.
+#' @param percentile Numeric scalar between 0 and 1 denoting the percentile to compute.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_percentile <- function(percentile, cols = character()) {
   verify_in_unit_interval("percentile", percentile, TRUE)
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_percentile, "agg_percentile", percentile=percentile, cols=cols))
 }
 
+#' @description
+#' Creates a Count aggregation that counts the number of rows in each aggregation group.
+#' Note that this operation is not supported in `agg_all_by()`.
+#' @param col String denoting the name of the new column to hold the counts of each aggregation group.
+#' @return Aggregation function to be used in `agg_by()`.
+#' @export
 agg_count <- function(col) {
   verify_string("col", col, TRUE)
   return(Aggregation$new(INTERNAL_agg_count, "agg_count", col=col))

R/rdeephaven/R/client_wrapper.R

@@ -1,8 +1,17 @@
+#' @description
+#' A Client is the entry point for interacting with the Deephaven server. It is used to create new tables,
+#' import data to and export data from the server, and run queries on the server.
 #' @export
 Client <- R6Class("Client",
   cloneable = FALSE,
   public = list(
     .internal_rcpp_object = NULL,
+
+    #' @description
+    #' Calls `initialize_for_xptr` if the first argument is an external pointer, and `initialize_for_target` if the
+    #' first argument is a string. In the latter case, the remaining keyword arguments are passed to `initialize_for_target`.
+    #' @param ... Either an external pointer to an existing client connection, or a string denoting the address
+    #' of a running Deephaven server followed by keyword arguments to `initialize_from_target`.
     initialize = function(...) {
       args <- list(...)
       if (length(args) == 1) {
@@ -19,10 +28,41 @@ Client <- R6Class("Client",
       }
       return(do.call(self$initialize_for_target, args))
     },
+
+    #' @description
+    #' Initializes a Client object using a pointer to an existing client connection.
+    #' @param xptr External pointer to an existing client connection.
     initialize_for_xptr = function(xptr) {
       verify_type("xptr", xptr, "externalptr", "XPtr", TRUE)
       self$.internal_rcpp_object = new(INTERNAL_Client, xptr)
     },
+
+    #' @description
+    #' Initializes a Client object and connects to a Deephaven server.
+    #' @param target String denoting the address of a Deephaven server, formatted as `"ip:port"`.
+    #' @param auth_type String denoting the authentication type. Can be `"anonymous"`, `"basic"`,
+    #' or any custom-built authenticator supported by the server, such as `"io.deephaven.authentication.psk.PskAuthenticationHandler"`.
+    #' Default is `anonymous`.
+    #' @param username String denoting the username, which only applies if `auth_type` is `basic`.
+    #' Username and password should not be used in conjunction with `auth_token`. Defaults to an empty string.
+    #' @param password String denoting the password, which only applies if `auth_type` is `basic`.
+    #' Username and password should not be used in conjunction with `auth_token`. Defaults to an empty string.
+    #' @param auth_token String denoting the authentication token. When `auth_type`
+    #' is `anonymous`, it will be ignored; when `auth_type` is `basic`, it must be
+    #' `"user:password"` or left blank; when `auth_type` is a custom-built authenticator, it must
+    #' conform to the specific requirement of that authenticator. This should not be used
+    #' in conjunction with `username` and `password`. Defaults to an empty string.
+    #' @param session_type String denoting the session type supported on the server.
+    #' Currently, `python` and `groovy` are supported. Defaults to `python`.
+    #' @param use_tls Whether or not to use a TLS connection. Defaults to `FALSE`.
+    #' @param tls_root_certs String denoting PEM encoded root certificates to use for TLS connection,
+    #' or `""` to use system defaults. Only used if `use_tls == TRUE`. Defaults to system defaults.
+    #' @param int_options List of name-value pairs for int-valued options to the underlying
+    #' grpc channel creation. Defaults to an empty list, which implies not using any channel options.
+    #' @param string_options List of name-value pairs for string-valued options to the underlying
+    #' grpc channel creation. Defaults to an empty list, which implies not using any channel options.
+    #' @param extra_headers List of name-value pairs for additional headers and values
+    #' to add to server requests. Defaults to an empty list, which implies not using any extra headers.
     initialize_for_target = function(
                           target,
                           auth_type = "anonymous",
@@ -138,22 +178,46 @@ Client <- R6Class("Client",
         client_options = options
       )
     },
+
+    #' @description
+    #' Creates an empty table on the server with 'size' rows and no columns.
+    #' @param size Non-negative integer specifying the number of rows for the new table.
+    #' @return TableHandle reference to the new table.
     empty_table = function(size) {
       verify_nonnegative_int("size", size, TRUE)
       return(TableHandle$new(self$.internal_rcpp_object$empty_table(size)))
     },
+
+    #' @description
+    #' Creates a ticking table on the server.
+    #' @param period ISO-8601-formatted string specifying the update frequency of the new table.
+    #' @param start_time Optional ISO-8601-formatted string specifying the start time of the table.
+    #' Defaults to now.
+    #' @return TableHandle reference to the new table.
     time_table = function(period, start_time = "now") {
       verify_string("period", period, TRUE)
       verify_string("start_time", start_time, TRUE)
       return(TableHandle$new(self$.internal_rcpp_object$time_table(period, start_time)))
     },
+
+    #' @description
+    #' Retrieves a reference to a named table on the server using its name.
+    #' @param name String denoting the name of the table to retrieve.
+    #' @return TableHandle reference to the named table.
     open_table = function(name) {
       verify_string("name", name, TRUE)
       if (!private$check_for_table(name)) {
         stop(paste0("The table '", name, "' does not exist on the server."))
       }
       return(TableHandle$new(self$.internal_rcpp_object$open_table(name)))
     },
+
+    #' @description
+    #' Imports a new table to the Deephaven server. Note that this new table is not automatically bound to
+    #' a variable name on the server. See `?TableHandle` for more information.
+    #' @param table_object R Data Frame, dplyr Tibble, Arrow Table, Arrow RecordBatchReader, or other supported table
+    #' containing the data to import to the server.
+    #' @return TableHandle reference to the new table.
     import_table = function(table_object) {
       table_object_class <- class(table_object)
       if (table_object_class[[1]] == "data.frame") {
@@ -170,14 +234,27 @@ Client <- R6Class("Client",
         stop(paste0("'table_object' must be a single data frame, tibble, arrow table, or record batch reader. Got an object of class ", table_object_class[[1]], "."))
       }
     },
+
+    #' @description
+    #' Retrieves a reference to a named table in the server using its Arrow Flight ticket.
+    #' @param ticket String denoting the Arrow Flight ticket.
+    #' @return TableHandle reference to the table.
     ticket_to_table = function(ticket) {
       verify_string("ticket", ticket, TRUE)
       return(TableHandle$new(self$.internal_rcpp_object$make_table_handle_from_ticket(ticket)))
     },
+
+    #' @description
+    #' Runs a script on the server. The script must be in the language that the server console was started with.
+    #' @param script String containing the code to be executed on the server.
     run_script = function(script) {
       verify_string("script", script, TRUE)
       self$.internal_rcpp_object$run_script(script)
     },
+
+    #' @description
+    #' Closes the client connection. After this method is called, any further server calls will
+    #' be undefined and will likely result in an error.
     close = function() {
       self$.internal_rcpp_object$close()
     }