document use of `add_overall`

[anajens]

Some time ago we talked about deprecating add_overall:

lets deprecate the add_overall function on gabe_tabletree_work and @anajens please start using add_overall_level for the release in 4 months.

Originally posted by @waddella in https://github.com/Roche/rtables/issues/172#issuecomment-799577274

However, I still think we need this function in some cases:

library(dplyr)
library(rtables)

# This does not give us a "total" column:
basic_table() %>%
  split_cols_by("ARM", split_fun = add_overall_level("All", first = FALSE)) %>%
  split_cols_by("ARMCD", split_fun = drop_split_levels) %>%
  add_colcounts() %>%
  analyze(vars = "SEX") %>%
  build_table(ex_adsl)

# This gives the correct overall column:
basic_table() %>%
  split_cols_by("ARM") %>%
  split_cols_by("ARMCD", split_fun = drop_split_levels) %>%
  add_overall_col("All Patients") %>%
  add_colcounts() %>%
  analyze(vars = "SEX") %>%
  build_table(ex_adsl)

[waddella]

as per discussion

• [ ] add add_* argument in to basic_table
• [ ] deprecate the add_overall_col function
• [ ] add a note in the documentation of basic_table
• [ ] add an FAQ vignette and an entry on total columns

[waddella]

revisiting this topic, add_overall_col is still useful to add a marginal column when there is nesting in column space. Hence, let's update the documentation when which method for adding an overall column should be used.