better explanations for alignment

Author: lorenzwalthert

vignettes/detect-alignment.Rmd

@@ -32,26 +32,38 @@ call(
 
 ```
 
-because no alignment detection was built in. With `strict = FALSE`, the spacing
+because no alignment detection was built in.^[With `strict = FALSE`, the spacing
 would have been kept, however, `strict = FALSE` has a number of other
-implications because it is in general less invasive (e.g. it would not add
-braces to the following expression, whereas `strict = TRUE` would):
+implications because it is in general less invasive. For example, it would not
+add braces and line breaks to "if (TRUE) return()".]
+
+styler >= 1.1.1.9003 detects aforementioned alignment for function calls. This
+vignette describes how aligned code is defined in styler and gives some examples
+so users can format their aligned code to match the definition styler uses to
+ensure their code is not unintentionally reformatted.
+
+An important definition used in the remainder is the one of a **column**. All
+arguments of a function call that have the same position but are placed on
+different lines form a column. The below call shows a call with two columns and
+two rows. Columns separate arguments of the function call, so the separator is
+the comma. The first row is named because all arguments are named, the second is
+unnamed:
 
 ```{r}
-if (TRUE)
-  call(another, arg)
+call(
+  # column 1  | column 2 |
+  abkj = f(2),         7,
+  more_ = "a", 2 # more
+)
 ```
 
-Back to the initial topic, styler >= 1.1.1.9003 detects the aforementioned
-alignment. This vignette describes how an aligned code is defined by styler and
-gives some examples so users can format their aligned code to match the
-definition styler uses to ensure their code is not unintentionally reformatted.
+## Function calls
 
-## function calls
+We generally distinguish the case of named and unnamed columns.
 
 ### Non-technical
 
-If all arguments in the first column are named: Make commas match position
+**If all arguments in the first column are named**: Make commas match position
 vertically and right align everything between commas
 
 ```{r}
@@ -63,20 +75,29 @@ fell(
   y  =   23,
   zz = NULL
 )
+
+# this works also with more than one column
+fell(
+  x  =    1, annoying = 3, 
+  y  =   23, # nothing in column 2 for row 2
+  zz = NULL, finally = ""
+)
 ```
 
-If not all arguments of the first column are named: Make all but the first
-column's commas match position vertically and right align everything between the
-commas, except before the first comma on a line, give priority to correctly
-indent.
+**If not all arguments of the first column are named:**^[In the below example,
+the first argument of the first column is named (`p = 2`), the second argument
+of the first column is not (`31`)] Make all but the first column's commas match
+position vertically and right align everything between the commas, except before
+the first comma on a line, give priority to correctly indent (i.e. left align).
 
 ```{r}
-# not all arguments of first column (f = NULL and 13231) named, hence, only 
+# not all arguments of first column named, hence, only 
 # commas of all but the first column must agree.
 gell(
-  2,        g = gg(x), n  = 3 * 3,
-  13231,  fds =    -1, gz = f / 3,
+  p = 2,   g = gg(x),  n = 3 * 3, #
+  31,    fds =    -1, gz = f / 3,
 )
+
 ```
 
 By *align everything in between the commas*, we mean put zero space before a
@@ -92,15 +113,31 @@ map(x, f,
 )
 ```
 
+**Examples**
+
+```{r}
+# tribble
+tibble::tribble(
+  ~key_here,  ~value_here,
+  "left",         "right", # comments are allowed
+  "long string",   "shrt" # columns can overlap ('~' above ',')
+)
+
+purrr::map(x, fun, # arguments on same line as opening brace are not considered
+  arg2  =    2, 
+  ar    = f(x)
+)
+```
+
 ## technical
 
 Function calls are aligned if **all** of the following conditions hold (for all
 but the very first line (i.e. `call(` below):
 
-* first column has same number of lag spaces. This basically means that the
-  indention is identical for all columns (except for the closing brace if it is
-  on its own line). The below example has one column, because the maximal number
-  of commas on one line is one.
+* all rows in first column has same number of lag spaces. This basically means
+  that the indention is identical for all columns (except for the closing brace
+  if it is on its own line). The below example has one column, because the
+  maximal number of commas on one line is one.
 
 ```{r}
 # holds
@@ -135,16 +172,16 @@ call(
 
 * All commas from all columns are aligned. This means that for every column, all
   commas must be on the same positions as the commas from the other lines. If
-  not all arguments are named in the first column, this column is not considered.
-  The reason to exclude the first column is that, as in the example below, it is
-  possible that some arguments are named while others are not. Then, it is not
-  generally possible to keep the first rule (i.e. indention identical across
-  lines) as well as ensuring that the comma does not have any spaces before it
-  and that the comma is aligned with the other lines. This is shown below with
-  the line `f(x, y),`. For this reason, the requirements exclude the first
-  column in such cases. The *holds* example shows that is is possible (but not
-  required) for named arguments to also have the commas separating the first and
-  second column aligned.
+  not all arguments are named in the first column, this column is not
+  considered. The reason to exclude the first column is that, as in the example
+  below, it is possible that some arguments are named while others are not.
+  Then, it is not generally possible to keep the first rule (i.e. indention
+  identical across lines) as well as ensuring that the comma does not have any
+  spaces before it and that the comma is aligned with the other lines. This is
+  shown below with the line `f(x, y),`. For this reason, the requirements
+  exclude the first column in such cases. The *holds* example shows that is is
+  possible (but not required) for named arguments to also have the commas
+  separating the first and second column aligned.
 
 ```{r}
 # holds
@@ -173,11 +210,11 @@ rge(
 )
 ```
 
-## comments
+## Comments
 
 not supported yet.
 
-## assignment
+## Assignment
 
 not supported yet.