Add docstrings to R Client

R/rdeephaven/R/aggregate_wrapper.R

@@ -14,80 +14,135 @@ Aggregation <- R6Class("Aggregation",
 
 ### All of the functions below return an instance of the above class
 
+#' @description
+#' Aggregation function that computes the first value of each column in `cols`, for each aggregation group.
+#' Intended to be used in a call to `TableHandle$agg_by()`.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_first <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_first(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the last value of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_last <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_last(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the minimum value of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_min <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_min(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the maximum value of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_max <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_max(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the sum of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_sum <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_sum(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the absolute sum of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_abs_sum <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_abs_sum(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the average of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_avg <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_avg(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the weighted average of each column in `cols`, for each aggregation group.
+#' @param wcol String denoting the name of the column to use as weights.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @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(wcol, cols)))
 }
 
+#' @description
+#' Aggregation function that computes the median of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_median <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_median(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the variance of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_var <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_var(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the standard deviation of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @export
 agg_std <- function(cols = character()) {
   verify_string("cols", cols, FALSE)
   return(Aggregation$new(INTERNAL_agg_std(cols)))
 }
 
+#' @description
+#' Aggregation function that computes the p-th 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 names of the columns to aggregate.
+#' @return Result of the aggregation.
 #' @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(percentile, cols)))
 }
 
+#' @description
+#' Aggregation function that counts the number of rows for each aggregation group.
+#' @param col String denoting the name of the new column to be created by counting entries in each group.
+#' @return Result of the aggregation.
 #' @export
 agg_count <- function(col) {
   verify_string("col", col, TRUE)

R/rdeephaven/R/client_wrapper.R

@@ -3,6 +3,32 @@ Client <- R6Class("Client",
   cloneable = FALSE,
   public = list(
     .internal_rcpp_object = NULL,
+    #' @description
+    #' Connect to a running Deephaven server.
+    #' @param target String denoting the address of the 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 = function(target,
                           auth_type = "anonymous",
                           username = "",
@@ -117,22 +143,46 @@ Client <- R6Class("Client",
         client_options = options
       )
     },
+
+    #' @description
+    #' Create 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
+    #' Create 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
+    #' Open a table named 'name' from the server if it exists.
+    #' @param name String denoting the name of the table to open from the server.
+    #' @return TableHandle reference to the requested 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
+    #' Import 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, a dplyr Tibble, an Arrow Table, or an Arrow RecordBatchReader
+    #' 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") {
@@ -149,10 +199,18 @@ 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
+    #' Run 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
+    #' Close 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()
     }