documentation enhancemenes

R/teal_transform_module.R

@@ -1,32 +1,34 @@
-#' Data module for `teal` transforms.
+#' Data module for `teal` transformations and output customization
 #'
 #' @description
 #' `r lifecycle::badge("experimental")`
 #'
-#' `teal_transform_module` creates a shiny-module to transform data in a `teal` application.
+#' `teal_transform_module` provides a `shiny` module that enables data transformations within a `teal` application
+#' and allows for customization of outputs generated by modules.
 #'
-#' # Transforming `teal` module's input
+#' # Transforming Module Inputs in `teal`
 #'
-#' This transformation happens after the data has passed through the filtering activity in teal. The
-#' transformed data is then sent to the server of the [teal_module()]. Process is handled by `teal`
-#' internals.
+#' Data transformations occur after data has been filtered in `teal`.
+#' The transformed data is then passed to the `server` of [`teal_module()`] and managed by `teal`'s internal processes.
+#' The primary advantage of `teal_transform_module` over custom modules is in its error handling, where all warnings and
+#' errors are managed by `teal`, allowing developers to focus on transformation logic.
 #'
-#' See vignette `vignette("data-transform-as-shiny-module", package = "teal")` for more details.
+#' For more details, see the vignette: `vignette("data-transform-as-shiny-module", package = "teal")`.
 #'
-#' # Decorating `teal` module's output
+#' # Customizing Module Outputs
 #'
-#' `teal_transform_module`'s purpose is to modify any object created in [`teal.data::teal_data`]. It means that an
-#' app-developer can use `teal_transform_module` to modify data but also outputted tables, listings and graphs.
-#' Some [`teal_modules`] enables app developer to inject custom shiny module to modify displayed output.
-#' To handle these `decorators` inside of your module use [ui_transform_data()] and [srv_transform_data].
-#' (todo: write more about how to handle decorators: they need to go through ui_args/srv_args and then be consumed by
-#' ui/srv_transform_data()... . Alternatively, decorators could be a [module()]'s argument)
+#' `teal_transform_module` also allows developers to modify any object created within [`teal.data::teal_data`].
+#' This means you can use it to customize not only datasets but also tables, listings, and graphs.
+#' Some [`teal_modules`] permit developers to inject custom `shiny` modules to enhance displayed outputs.
+#' To manage these `decorators` within your module, use [`ui_transform_data()`] and [`srv_transform_data()`].
+#' (For further guidance on managing decorators, refer to `ui_args` and `srv_args` in the vignette documentation.)
+#'
+#' See the vignette `vignette("decorate-modules-output", package = "teal")` for additional examples.
 #'
 #' # `server` as a language
 #'
-#' Server function in `teal_transform_module` must return `reactive` containing [teal.data::teal_data] object.
-#' Consider sinmple transform which doesn't require any advanced reactivity, example `server` might have a
-#' following form:
+#' The `server` function in `teal_transform_module` must return a reactive [`teal.data::teal_data`] object.
+#' For simple transformations without complex reactivity, the `server` function might look like this:s
 #'
 #' ```
 #' function(id, data) {
@@ -42,22 +44,21 @@
 #' }
 #' ```
 #'
-#' Above can be simplified to presented below, where `level` will be automatically substituted with
-#' the respective input matched by its name.
+#' The example above can be simplified using `make_teal_transform_server`, where `level` is automatically matched to the
+#' corresponding `input` parameter:
 #'
 #' ```
-#' make_transform_data(expr = expression(x <- subset(x, col == level)))
+#' make_teal_transform_server(expr = expression(x <- subset(x, col == level)))
 #' ```
 #' @inheritParams teal_data_module
-#' @param server (`function(id, data)` or `language`)
-#' `shiny` module server function; that takes `id` and `data` argument,
-#' where the `id` is the module id and `data` is the reactive `teal_data` input.
-#' The server function must return reactive expression containing `teal_data` object.
-#' To simplify, use [make_teal_transform_server()].
+#' @param server (`function(id, data)` or `expression`)
+#' A `shiny` module server function that takes `id` and `data` as arguments, where `id` is the module id and `data`
+#' is the reactive `teal_data` input. The `server` function must return a reactive expression containing a `teal_data`
+#' object. For simplified syntax, use [`make_teal_transform_server()`].
 #' @param datanames (`character`)
-#' Names of the datasets that are relevant for the module. The
-#' filter panel will only display filters for specified `datanames`. The keyword `"all"` will show
-#' filters of all datasets. `datanames` will be automatically appended to the [modules()] `datanames`.
+#' Specifies the names of datasets relevant to the module. Only filters for the specified `datanames` will be displayed
+#' in the filter panel. The keyword `"all"` can be used to display filters for all datasets. `datanames` are
+#' automatically appended to the [`modules()`] `datanames`.
 #'
 #'
 #' @examples