doc: review function families

Author: davidgohel

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: flextable
 Title: Functions for Tabular Reporting
-Version: 0.9.12.004
+Version: 0.9.12.005
 Authors@R: c(
     person("David", "Gohel", , "david.gohel@ardata.fr", role = c("aut", "cre")),
     person("ArData", role = "cph"),

R/00-deprecated.R

@@ -0,0 +1,14 @@
+#' @keywords internal
+#' @title flextable old functions
+#' @description The function is maintained for compatibility with old codes
+#' mades by users but be aware it produces the same exact object than [flextable()].
+#' This function should be deprecated then removed in the next versions.
+#' @param data dataset
+#' @param col_keys columns names/keys to display. If some column names are not in
+#' the dataset, they will be added as blank columns by default.
+#' @param cwidth,cheight initial width and height to use for cell sizes in inches.
+#' @export
+regulartable <- function(data, col_keys = names(data), cwidth = .75, cheight = .25) {
+  .Deprecated(new = "flextable")
+  flextable(data = data, col_keys = col_keys, cwidth = cwidth, cheight = cheight)
+}

R/05_content.R

@@ -871,6 +871,7 @@ as_qmd <- function(x, display = x) {
 #' @return The path to the installed extension (invisibly).
 #' @seealso [as_qmd()] for creating Quarto markdown chunks,
 #' [knit_print.flextable()] for rendering options in knitr documents.
+#' @family flextable_configuration
 #' @examples
 #' \dontrun{
 #' use_flextable_qmd()
@@ -923,7 +924,7 @@ use_flextable_qmd <- function(path = ".", quiet = FALSE) {
 #' function [as_chunk()].
 #' @param list_values a list of chunk elements that are defining
 #' the paragraph content. If specified argument `...` is unused.
-#' @family functions for mixed content paragraphs
+#' @family cell_content_composition
 #' @seealso [as_chunk()], [minibar()],
 #' [as_image()], [hyperlink_text()]
 #' @examples

R/append_chunk.R

@@ -6,7 +6,7 @@
 #' @param ... chunks to be appened, see [as_chunk()], [gg_chunk()] and other
 #' chunk elements for paragraph.
 #' @seealso [as_chunk()], [as_sup()], [as_sub()], [colorize()]
-#' @family functions for mixed content paragraphs
+#' @family cell_content_composition
 #' @examples
 #' library(flextable)
 #' img.file <- file.path(R.home("doc"), "html", "logo.jpg")
@@ -60,7 +60,7 @@ append_chunks <- function(x, ..., i = NULL, j = NULL, part = "body") {
 #' @inheritParams args_selectors_without_all
 #' @param ... chunks to be prepended, see [as_chunk()], [gg_chunk()] and other
 #' chunk elements for paragraph.
-#' @family functions for mixed content paragraphs
+#' @family cell_content_composition
 #' @examples
 #' x <- flextable(head(iris))
 #' x <- prepend_chunks(

R/as_flextable.R

@@ -7,7 +7,7 @@
 #' @param x object to be transformed as flextable
 #' @param ... arguments for custom methods
 #' @export
-#' @family as_flextable methods
+#' @family flextable_constructors
 as_flextable <- function(x, ...) {
   UseMethod("as_flextable")
 }
@@ -881,6 +881,7 @@ as_flextable.pam <- function(x, digits = 4, ...) {
 #' flextable::use_model_printer()
 #' ```
 #' @seealso [use_df_printer()], [flextable()]
+#' @family flextable_configuration
 use_model_printer <- function() {
   fun <- function(x, ...) knitr::knit_print(as_flextable(x))
   registerS3method("knit_print", "lm", fun)

R/augment_rows.R

@@ -40,7 +40,7 @@
 #' )
 #' ft
 #' @export
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 set_header_labels <- function(x, ..., values = NULL) {
   if (!inherits(x, "flextable")) {
     stop(sprintf("Function `%s` supports only flextable objects.", "set_header_labels()"))
@@ -105,7 +105,7 @@ set_header_labels <- function(x, ..., values = NULL) {
 #' the flextable, i.e. an header, footer or the body.
 #'
 #' @inheritParams args_x_part_no_all
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 #' @examples
 #' ft <- flextable(head(iris))
 #' ft <- delete_part(x = ft, part = "header")
@@ -156,7 +156,7 @@ delete_rows_from_part <- function(x, i) {
 
 #' @export
 #' @title Delete flextable rows
-#'
+#' @family table_structure
 #' @description The function removes one or more rows
 #' from a 'flextable'.
 #' @details
@@ -235,7 +235,7 @@ delete_colums_from_part <- function(x, j) {
 #' They will have to be redone after this operation or
 #' performed only after this deletion.
 #' @inheritParams args_x_j
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 #' @examples
 #' ft <- flextable(head(iris))
 #' ft <- delete_columns(ft, j = "Species")
@@ -355,7 +355,7 @@ add_rows_to_tabpart <- function(x, rows, first = FALSE) {
 #'
 #' ft <- theme_booktabs(ft)
 #' ft
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 #' @seealso [flextable()]
 add_body <- function(x, top = TRUE, ..., values = NULL) {
   if (!inherits(x, "flextable")) {
@@ -410,7 +410,7 @@ add_body <- function(x, top = TRUE, ..., values = NULL) {
 #' ft_1 <- theme_booktabs(ft_1, bold_header = TRUE)
 #' ft_1 <- align(ft_1, align = "center", part = "all")
 #' ft_1
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 add_header <- function(x, top = TRUE, ..., values = NULL) {
   if (!inherits(x, "flextable")) {
     stop(sprintf("Function `%s` supports only flextable objects.", "add_header()"))
@@ -452,7 +452,7 @@ add_header <- function(x, top = TRUE, ..., values = NULL) {
 #' )
 #' ft <- align(ft, part = "footer", align = "right", j = 1:4)
 #' ft
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 add_footer <- function(x, top = TRUE, ..., values = NULL) {
   if (!inherits(x, "flextable")) {
     stop(sprintf("Function `%s` supports only flextable objects.", "add_footer()"))
@@ -538,7 +538,7 @@ add_footer <- function(x, top = TRUE, ..., values = NULL) {
 #' )
 #' ft_2 <- theme_box(ft_2)
 #' ft_2
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 #' @seealso [flextable()], [set_caption()]
 add_body_row <- function(x, top = TRUE, values = list(), colwidths = integer(0)) {
   if (!inherits(x, "flextable")) {
@@ -650,7 +650,7 @@ add_body_row <- function(x, top = TRUE, values = list(), colwidths = integer(0))
 #' )
 #' ft_2 <- theme_box(ft_2)
 #' ft_2
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 #' @seealso [flextable()], [set_caption()]
 add_header_row <- function(x, top = TRUE, values = character(0), colwidths = integer(0)) {
   if (!inherits(x, "flextable")) {
@@ -722,7 +722,7 @@ add_header_row <- function(x, top = TRUE, values = character(0), colwidths = int
 #'
 #' Labels can be formatted with [as_paragraph()].
 #' @inheritParams add_body_row
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 #' @seealso [flextable()], [set_caption()]
 #' @examples
 #' library(flextable)
@@ -834,7 +834,7 @@ data_from_char <- function(values, colwidths, col_keys) {
 #' be added as a new row.
 #' @param top should the row be inserted at the top
 #' or the bottom. Default to TRUE.
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 #' @examples
 #' # ex 1----
 #' ft_1 <- flextable(head(iris))
@@ -895,7 +895,7 @@ add_header_lines <- function(x, values = character(0), top = TRUE) {
 #' spans all columns (all cells merged into one). Useful for adding
 #' footnotes or source notes below the table.
 #' @inheritParams add_header_lines
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 #' @examples
 #' ft_1 <- flextable(head(iris))
 #' ft_1 <- add_footer_lines(ft_1,
@@ -1018,7 +1018,7 @@ set_part_df <- function(x, mapping = NULL, key = "col_keys", part) {
 #' ft_1 <- theme_vanilla(ft_1)
 #' ft_1 <- fix_border_issues(ft_1)
 #' ft_1
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 set_header_df <- function(x, mapping = NULL, key = "col_keys") {
   if (!inherits(x, "flextable")) {
     stop(sprintf("Function `%s` supports only flextable objects.", "set_header_df()"))
@@ -1077,7 +1077,7 @@ set_footer_df <- function(x, mapping = NULL, key = "col_keys") {
 #' to use for splitting.
 #' @param fixed logical. If TRUE match `split` exactly,
 #' otherwise use regular expressions.
-#' @family functions for row and column operations in a flextable
+#' @family table_structure
 #' @examples
 #' library(flextable)
 #'

R/body_add_flextable.R

@@ -2,6 +2,7 @@
 #' @title Add flextable into a Word document
 #' @description Add a flextable into a Word document
 #' created with 'officer'.
+#' @family officer_integration
 #'
 #' @details
 #' Use the [paginate()] function to define whether the table should
@@ -149,6 +150,7 @@ body_add_flextable <- function(x, value,
 
 #' @export
 #' @title Add flextable at bookmark location in a Word document
+#' @family officer_integration
 #' @description
 #' Use this function if you want to replace a paragraph containing
 #' a bookmark with a flextable. As a side effect, the bookmark will be lost.

R/compose.R

@@ -54,7 +54,7 @@
 #' ft_2 <- autofit(ft_2)
 #' ft_2
 #' @export
-#' @family functions for mixed content paragraphs
+#' @family cell_content_composition
 #' @seealso [fp_text_default()], [as_chunk()], [as_b()], [as_word_field()], [labelizor()]
 compose <- function(x, i = NULL, j = NULL, value, part = "body", use_dot = FALSE) {
   if (!inherits(x, "flextable")) {
@@ -160,6 +160,7 @@ mk_par <- compose
 #' )
 #'
 #' ft_1
+#' @family cell_content_composition
 labelizor <- function(x, j = NULL, labels, part = "all") {
   if (!inherits(x, "flextable")) {
     stop(sprintf("Function `%s` supports only flextable objects.", "labelizor()"))

R/defaults.R

@@ -131,7 +131,7 @@ flextable_global$defaults <- default_flextable_settings
 #' ft_2
 #'
 #' do.call(set_flextable_defaults, old)
-#' @family functions related to themes
+#' @family themes_and_defaults
 #' @importFrom utils modifyList
 set_flextable_defaults <- function(
     font.family = NULL,
@@ -327,7 +327,7 @@ init_flextable_defaults <- function() {
 #' @return a list containing default values.
 #' @examples
 #' get_flextable_defaults()
-#' @family functions related to themes
+#' @family themes_and_defaults
 get_flextable_defaults <- function() {
   x <- flextable_global$defaults
   class(x) <- "flextable_defaults"
@@ -403,7 +403,7 @@ print.flextable_defaults <- function(x, ...) {
 #'
 #' init_flextable_defaults()
 #'
-#' @family functions for defining formatting properties
+#' @family default_formatting_properties
 #' @seealso [as_chunk()], [compose()], [append_chunks()], [prepend_chunks()]
 fp_text_default <- function(color = flextable_global$defaults$font.color,
                             font.size = flextable_global$defaults$font.size,
@@ -460,7 +460,7 @@ fp_text_default <- function(color = flextable_global$defaults$font.color,
 #'
 #' init_flextable_defaults()
 #'
-#' @family functions for defining formatting properties
+#' @family default_formatting_properties
 #' @seealso [hline()], [vline()]
 fp_border_default <- function(
     color = flextable_global$defaults$border.color,

R/df_printer.R

@@ -39,7 +39,7 @@
 #' Default to TRUE.
 #' * `ft_color_coltype`: Color to use for column types.
 #' Default to "#999999".
-#' @family flextable print function
+#' @family flextable_output_export
 #' @examples
 #' df_printer(head(mtcars))
 df_printer <- function(dat, ...) {
@@ -79,6 +79,7 @@ df_printer <- function(dat, ...) {
 #' flextable::use_df_printer()
 #' ```
 #' @seealso [df_printer()], [flextable()]
+#' @family flextable_configuration
 use_df_printer <- function() {
   registerS3method("knit_print", "data.frame", df_printer)
   registerS3method("knit_print", "data.table", df_printer)