Docs update

R/layout-quad-operator.R

@@ -1,24 +1,26 @@
-#' Modify `-` Operator Context in `quad_layout()`
+#' Modify Context for the `-` Operator in `quad_layout()`
 #'
 #' @description
-#' `r lifecycle::badge('experimental')` Wrapping objects with `with_quad`
-#' allows you to change the context of the subtraction `-` operator in
-#' `quad_layout()`.
+#' `r lifecycle::badge('experimental')` The `with_quad` function allows you to
+#' adjust the context in which the subtraction `-` operator is applied within
+#' `quad_layout()`. This function wraps objects to specify their target layout
+#' contexts when using `-` in `quad_layout()`.
 #'
-#' @param x Objects to add to the layout using the `-` operator.
-#' @param position A string containing one or more of `r oxford_and(.tlbr)`
-#' indicating which annotation stack should be used as the context. If `NULL`,
-#' the context will default to the [`quad_layout()`] itself. By default,
-#' `waiver()` is used, which triggers the following behavior: If the current
-#' active context in [`quad_layout()`] is `top` or `bottom`, the operator will
-#' also act on the corresponding `bottom` or `top` annotation. If the context is
-#' `left` or `right`, the operator will also act on the `right` or `left`
-#' annotation, respectively. If there is no active annotation stack, it defaults
-#' to `NULL`.
-#' @param main A single boolean value indicates whether to apply `x` for the
-#' main plot.
-#' @return The input object with an additional attribute that specifies the
-#' selected context.
+#' @param x The object to be added to the layout using the `-` operator.
+#' @param position A string specifying one or more positions—
+#' `r oxford_and(.tlbr)`— to indicate the annotation stack context for the
+#' operator [`-`][layout-operator]. By default, `waiver()` is used, which sets
+#' the behavior as follows: if the active context in `quad_layout()` is `top` or
+#' `bottom`, the operator will also apply to the corresponding `bottom` or `top`
+#' annotation, respectively. Similarly, if the context is `left` or `right`, the
+#' operator applies to the `right` or `left` annotation. When no annotation
+#' stack is active, the context defaults to `NULL`.
+#' @param main A single boolean value indicating whether `x` should apply to the
+#' main plot, used only when `position` is not `NULL`. By default, if `position`
+#' is `waiver()` and the active context of `quad_layout()` is an annotation
+#' stack, `main` will be set to `TRUE`; otherwise, it defaults to `FALSE`.
+#' @return The original object with an added attribute that sets the specified
+#' layout context.
 #' @export
 with_quad <- function(x, position = waiver(), main = NULL) {
     assert_layout_position(position)

vignettes/heatmap-layout.Rmd

@@ -341,34 +341,49 @@ my_plot +
 Along with the `-` operator, `with_quad()` can be used to modify the
 operated context in `ggheatmap()`/`quad_layout()`.
 
-It accepts three arguments: the object operated on by the `-` operator and the
-operated context, and a single boolean value indicates whether we should operate
-on the main plot of `ggheatmap()`/`quad_layout()`.
-
-By default, if the current active context in `ggheatmap()`/`quad_layout()` is
-`top` or `bottom`, the operator will also act on the corresponding `bottom` or
-`top` annotation. If the context is `left` or `right`, the operator will also
-act on the `right` or `left` annotation, respectively. If there is no active
-annotation stack, it defaults to `NULL` (this behavior differs in
-`stack_layout()`; refer to `vignette("stack-layout")` for more details).
+This function accepts three arguments:
+ 1. **x**: The object to be applied using the `-` operator.
+ 2. **position**: A string indicating the annotation stack to target (`top`,
+  `bottom`, `left`, `right`, or combinations thereof). This specifies the
+  context for applying `x`. 
+ 3. **main**: A boolean that determines whether `x` should also apply to the main
+  plot within `ggheatmap()`/`quad_layout()`.
+
+By default, when the active context in `ggheatmap()`/`quad_layout()` is set to
+`top` or `bottom`, the `-` operator will apply changes not only to that
+annotation but also to the opposite one (i.e., bottom if top is active, and vice
+versa). The same principle applies to the left and right contexts. In these
+cases, the object will also be applied to the main plot by default unless
+specified otherwise. If no annotation stack is active, `with_quad()` defaults to
+`NULL`. (this behavior differs in `stack_layout()`; refer to
+`vignette("stack-layout")` for more details) 
+
 ```{r}
 my_plot +
     # Change the active layout to the left annotation
     anno_left() -
     # Modify the background of all plots in the left and the opposite annotation
+    # in this way, the `main` argument by default would be `TRUE`
     with_quad(theme(plot.background = element_rect(fill = "red")))
 ```
 
-The second argument can be a string containing one or more of `r
+The `position` argument can be a string containing one or more of `r
 ggalign:::oxford_and(ggalign:::.tlbr)`, indicating which annotation stack should
-be used as the context. The above example is equivalent to: 
+be used as the context. When the `position` argument is manually set, the
+default value of the main argument will be `FALSE`. The example above is
+equivalent to: 
 ```{r}
 my_plot -
     # Modify the background of all plots in the left and right annotation
-    with_quad(theme(plot.background = element_rect(fill = "red")), "lr")
+    # and the main plot
+    with_quad(
+        theme(plot.background = element_rect(fill = "red")),
+        "lr", main = TRUE
+    )
 ```
 
-If it is `NULL`, it removes any active annotation stack:
+Setting `position` to `NULL` removes any active annotation stack, meaning the
+object will apply to all plots in the layout, including annotation stacks: 
 ```{r}
 my_plot -
     # Modify the background of all plots

vignettes/plot-options.Rmd

@@ -14,14 +14,19 @@ knitr::opts_chunk$set(
 )
 ```
 
-Waiting for complete ...
+Plot options control the action of plots in the layout, they can be set at the
+layout level to define global options for all plots in the layout, or they can
+be applied to individual plots.
+
+ - To set a plot option for a single plot, simply use the `+` operator
+ - To set a plot aption in the layout level, simply use the `-` operator.
 
 Currently, the package provides three actions (each prefixed with `plot_`):
+  - `plot_theme`: Sets the default theme for the plot.
   - `plot_data`: Transforms the plot data. Many functions in this package
   require a specific data format to align observations, `plot_data()` helps
-  reformat data frames as needed. 
+  reformat data frames as needed.
   - `plot_align`: Defines alignment specifications for plots within the layout.
-  - `plot_theme`: Sets the default theme for the plot.
 
 ```{r setup}
 library(ggalign)
@@ -215,7 +220,7 @@ heatmap_collect_all_guides +
     plot_align(guides = "l", free_spaces = "l")
 ```
 
-In `ggheatmap()` and `quad_layout()`, the behavior of the `free_spaces` and
+In `ggheatmap()`/`quad_layout()`, the behavior of the `free_spaces` and
 `free_labs` arguments differs from other arguments in `plot_align()` when
 inheriting from the parent layout:
   - For `top` and `bottom` annotations, it inherits from the left ("l") and