📚 document features inside package

Author: Ryan Patrick Kyle

R/dash.R

@@ -12,7 +12,10 @@
 #'   assets_ignore = '',
 #'   serve_locally = TRUE,
 #'   routes_pathname_prefix = '/',
-#'   requests_pathname_prefix = '/'
+#'   requests_pathname_prefix = '/',
+#'   external_scripts = NULL,
+#'   external_stylesheets = NULL,
+#'   suppress_callback_exceptions = FALSE
 #' )
 #'
 #' @section Arguments:
@@ -88,11 +91,32 @@
 #'     The latter may offer improved performance relative to callbacks written
 #'     in R.
 #'   }
+#'   \item{`callback_context()`}{
+#'     The `callback_context` method permits retrieving the inputs which triggered 
+#'     the firing of a given callback, and allows introspection of the input/state 
+#'     values given their names. It is only available from within a callback; 
+#'     attempting to use this method outside of a callback will result in a warning.
+#'   }
 #'   \item{`run_server(host =  Sys.getenv('DASH_HOST', "127.0.0.1"),
 #'    port = Sys.getenv('DASH_PORT', 8050), block = TRUE, showcase = FALSE, ...)`}{
-#'     Launch the application. If provided, `host`/`port` set
-#'     the `host`/`port` fields of the underlying [fiery::Fire] web
-#'     server. The `block`/`showcase`/`...` arguments are passed along
+#'     The `run_server` method has 13 formal arguments, several of which are optional:
+#'     \describe{
+#'       \item{host}{Character. A string specifying a valid IPv4 address for the Fiery server, or `0.0.0.0` to listen on all addresses. Default is `127.0.0.1` Environment variable: `DASH_HOST`.}
+#'       \item{port}{Integer. Specifies the port number on which the server should listen (default is `8050`). Environment variable: `DASH_PORT`.}
+#'       \item{block}{Logical. Start the server while blocking console input? Default is `TRUE`.}
+#'       \item{showcase}{Logical. Load the Dash application into the default web browser when server starts? Default is `FALSE`.}
+#'       \item{use_viewer}{Logical. Load the Dash application into RStudio's viewer pane? Requires that `host` is either `127.0.0.1` or `localhost`, and that Dash application is started within RStudio; if `use_viewer = TRUE` and these conditions are not satsified, the user is warned and the app opens in the default browser instead. Default is `FALSE`.}
+#'       \item{debug}{Logical. Enable/disable all the dev tools unless overridden by the arguments or environment variables. Default is `FALSE` when called via `run_server`. Environment variable: `DASH_DEBUG`.}
+#'       \item{dev_tools_ui}{Logical. Show Dash's dev tools UI? Default is `TRUE` if `debug == TRUE`, `FALSE` otherwise. Environment variable: `DASH_UI`.}
+#'       \item{dev_tools_hot_reload}{Logical. Activate hot reloading when app, assets, and component files change? Default is `TRUE` if `debug == TRUE`, `FALSE` otherwise. Requires that the Dash application is loaded using `source()`, so that `srcref` attributes are available for executed code. Environment variable: `DASH_HOT_RELOAD`.}
+#'       \item{dev_tools_hot_reload_interval}{Numeric. Interval in seconds for the client to request the reload hash. Default is `3`. Environment variable: `DASH_HOT_RELOAD_INTERVAL`.}
+#'       \item{dev_tools_hot_reload_watch_interval}{Numeric. Interval in seconds for the server to check asset and component folders for changes. Default `0.5`. Environment variable: `DASH_HOT_RELOAD_WATCH_INTERVAL`.}
+#'       \item{dev_tools_props_check}{Logical. Validate the types and values of Dash component properties? Default is `TRUE` if `debug == TRUE`, `FALSE` otherwise. Environment variable: `DASH_PROPS_CHECK`.}
+#'       \item{dev_tools_prune_errors}{Logical. Reduce tracebacks to just user code, stripping out Fiery and Dash pieces? Only available with debugging. `TRUE` by default, set to `FALSE` to see the complete traceback. Environment variable: `DASH_PRUNE_ERRORS`.}
+#'       \item{dev_tools_silence_routes_logging}{Logical. Replace Fiery's default logger with `dashLogger` instead (will remove all routes logging)? Enabled with debugging by default because hot reload hash checks generate a lot of requests.}
+#'     }
+#'     Starts the Fiery server in local mode. If a parameter can be set by an environment variable, that is listed too. Values provided here take precedence over environment variables.
+#'     Launch the application. If provided, `host`/`port` set the `host`/`port` fields of the underlying [fiery::Fire] web server. The `block`/`showcase`/`...` arguments are passed along
 #'     to the `ignite()` method of the [fiery::Fire] server.
 #'   }
 #' }
@@ -609,14 +633,14 @@ Dash <- R6::R6Class(
                           block = TRUE, 
                           showcase = FALSE, 
                           use_viewer = FALSE,
-                          dev_tools_prune_errors = TRUE, 
-                          debug = FALSE, 
-                          dev_tools_ui = NULL,
-                          dev_tools_props_check = NULL,
-                          dev_tools_hot_reload = NULL,
-                          dev_tools_hot_reload_interval = 3,
-                          dev_tools_hot_reload_watch_interval = 0.5,
-                          dev_tools_silence_routes_logging = NULL,
+                          dev_tools_prune_errors = Sys.getenv('DASH_PRUNE_ERRORS', TRUE), 
+                          debug = Sys.getenv('DASH_DEBUG', FALSE), 
+                          dev_tools_ui = Sys.getenv('DASH_UI', NULL),
+                          dev_tools_props_check = Sys.getenv('DASH_PROPS_CHECK', NULL),
+                          dev_tools_hot_reload = Sys.getenv('DASH_HOT_RELOAD', NULL),
+                          dev_tools_hot_reload_interval = Sys.getenv('DASH_HOT_RELOAD_INTERVAL', 3),
+                          dev_tools_hot_reload_watch_interval = Sys.getenv('DASH_HOT_RELOAD_WATCH_INTERVAL', 0.5),
+                          dev_tools_silence_routes_logging = Sys.getenv('DASH_SILENCE_ROUTES_LOGGING', NULL),
                           ...) {
       if (exists("dash_nested_fiery_server", env=parent.frame(1))) {
         # fiery is attempting to launch a server within a server, abort gracefully
@@ -639,7 +663,7 @@ Dash <- R6::R6Class(
       # set the modtime to track state of the Dash app directory
       # this calls getAppPath, which will try three approaches to
       # identifying the local app path (depending on whether the app
-      # is invoked via script, source(), or executed dire ctly from console)
+      # is invoked via script, source(), or executed directly from console)
       if (is.null(dev_tools_ui) && debug || isTRUE(dev_tools_ui)) {
         self$config$ui <- TRUE
       } else {

R/utils.R

@@ -1099,6 +1099,7 @@ dashLogger <- function(event = NULL,
   }
 }
 
+#' @export
 clientsideFunction <- function(namespace, function_name) {
   return(list(namespace=namespace, function_name=function_name))
 }