Review examples

R/class-comment.R

@@ -84,17 +84,18 @@ wbComment <- R6::R6Class(
 # TODO write_comment() should leverage wbWorkbook$addComment() more
 # TODO remove_comment() should leverage wbWorkbook$remove_comment() more
 
-#' @name create_comment
-#' @title Create, write and remove comments
-#' @description The comment functions (create, write and remove) allow the
+#' Create, write and remove comments
+#'
+#' The comment functions (create, write and remove) allow the
 #' modification of comments. In newer spreadsheet software they are called
 #' notes, while they are called comments in openxml. Modification of what
 #' newer spreadsheet software now calls comment is possible via
 #' [wb_add_thread()].
+#'
 #' @param text Comment text. Character vector.
-#' @param author Author of comment. Character vector of length 1
+#' @param author Author of comment. A string.
 #' @param style A Style object or list of style objects the same length as comment vector.
-#' @param visible TRUE or FALSE. Is comment visible.
+#' @param visible `TRUE` or `FALSE`. Is comment visible?
 #' @param width Textbox integer width in number of cells
 #' @param height Textbox integer height in number of cells
 #' @export
@@ -105,21 +106,21 @@ wbComment <- R6::R6Class(
 #'
 #' # write comment without author
 #' c1 <- create_comment(text = "this is a comment", author = "")
-#' write_comment(wb, 1, col = "B", row = 10, comment = c1)
+#' wb$add_comment(dims = "B10", comment = c1)
 #'
 #' # Write another comment with author information
 #' c2 <- create_comment(text = "this is another comment", author = "Marco Polo")
-#' write_comment(wb, 1, col = "C", row = 10, comment = c2)
+#' wb$add_comment(sheet = 1, dims = "C10", comment = c2)
 #'
 #' # write a styled comment with system author
 #' s1 <- create_font(b = "true", color = wb_color(hex = "FFFF0000"), sz = "12")
 #' s2 <- create_font(color = wb_color(hex = "FF000000"), sz = "9")
 #' c3 <- create_comment(text = c("This Part Bold red\n\n", "This part black"), style = c(s1, s2))
 #'
-#' write_comment(wb, 1, col = 6, row = 3, comment = c3)
+#' wb$add_comment(sheet = 1, dims = wb_dims(3, 6), comment = c3)
 #'
-#' # remove the first comment
-#' remove_comment(wb, 1, col = "B", row = 10)
+#' # remove the first comment c1
+#' wb$remove_comment(1, dims = "B10")
 create_comment <- function(text,
   author = Sys.info()[["user"]],
   style = NULL,

R/class-workbook-wrappers.R

@@ -3,25 +3,24 @@
 #'
 #' Create a new Workbook object
 #'
+#' `theme` can be one of
+#' "Atlas", "Badge", "Berlin", "Celestial", "Crop", "Depth", "Droplet",
+#' "Facet", "Feathered", "Gallery", "Headlines", "Integral", "Ion",
+#' "Ion Boardroom", "Madison", "Main Event", "Mesh", "Office Theme",
+#' "Old Office Theme", "Organic", "Parallax", "Parcel", "Retrospect",
+#' "Savon", "Slice", "Vapor Trail", "View", "Wisp", "Wood Type"
+#'
 #' @param creator Creator of the workbook (your name). Defaults to login username
-#' @param title Workbook properties title
-#' @param subject Workbook properties subject
-#' @param category Workbook properties category
+#' @param title,subject,category Workbook property, a string.
 #' @param datetime_created The time of the workbook is created
-#' @param theme Optional theme identified by string or number
+#' @param theme Optional theme identified by string or number.
+#'   See **Details** for options.
 #' @param ... additional arguments
 #' @return A [wbWorkbook] object
 #'
 #' @export
 #' @family workbook wrappers
 #'
-#' @details
-#' "Atlas", "Badge", "Berlin", "Celestial", "Crop", "Depth", "Droplet",
-#' "Facet", "Feathered", "Gallery", "Headlines", "Integral", "Ion",
-#' "Ion Boardroom", "Madison", "Main Event", "Mesh", "Office Theme",
-#' "Old Office Theme", "Organic", "Parallax", "Parcel", "Retrospect",
-#' "Savon", "Slice", "Vapor Trail", "View", "Wisp", "Wood Type"
-#'
 #' @examples
 #' ## Create a new workbook
 #' wb <- wb_workbook()
@@ -916,9 +915,9 @@ wb_remove_row_heights <- function(wb, sheet = current_sheet(), rows) {
 #' @param wb A workbook object
 #' @param sheet A name or index of a worksheet
 #' @param dims Worksheet dimension, single cell ("A1") or cell range ("A1:D4")
-#' @param row_offset,col_offset offset for column and row
-#' @param width Width of figure. Defaults to `6`in.
-#' @param height Height of figure . Defaults to `4`in.
+#' @param row_offset,col_offset Offset for column and row
+#' @param width Width of figure. Defaults to `6` in.
+#' @param height Height of figure . Defaults to `4` in.
 #' @param file_type File type of image
 #' @param units Units of width and height. Can be `"in"`, `"cm"` or `"px"`
 #' @param dpi Image resolution
@@ -931,7 +930,7 @@ wb_remove_row_heights <- function(wb, sheet = current_sheet(), rows) {
 #' wb <- wb_workbook()
 #'
 #' ## Add a worksheet
-#' wb$add_worksheet("Sheet 1", gridLines = FALSE)
+#' wb$add_worksheet("Sheet 1", grid_lines = FALSE)
 #'
 #' ## create plot objects
 #' require(ggplot2)
@@ -943,11 +942,11 @@ wb_remove_row_heights <- function(wb, sheet = current_sheet(), rows) {
 #'
 #' ## Insert currently displayed plot to sheet 1, row 1, column 1
 #' print(p1) # plot needs to be showing
-#' wb$add_plot(1, width = 5, height = 3.5, fileType = "png", units = "in")
+#' wb$add_plot(1, width = 5, height = 3.5, file_type = "png", units = "in")
 #'
 #' ## Insert plot 2
 #' print(p2)
-#' wb$add_plot(1, dims = "J2", width = 16, height = 10, fileType = "png", units = "cm")
+#' wb$add_plot(1, dims = "J2", width = 16, height = 10, file_type = "png", units = "cm")
 #'
 #' }
 wb_add_plot <- function(
@@ -2122,12 +2121,12 @@ wb_remove_tables <- function(wb, sheet = current_sheet(), table, remove_data = T
 #' wb <- wb_group_cols(wb, "AirPass", 8:10, collapsed = TRUE)
 #' wb <- wb_group_cols(wb, "AirPass", 11:13)
 #'
-#' @name wb_grouping
+#' @name workbook_grouping
 #' @family workbook wrappers
 NULL
 
 #' @export
-#' @rdname wb_grouping
+#' @rdname workbook_grouping
 wb_group_cols <- function(wb, sheet = current_sheet(), cols, collapsed = FALSE, levels = NULL) {
   assert_workbook(wb)
   wb$clone()$group_cols(
@@ -2139,15 +2138,15 @@ wb_group_cols <- function(wb, sheet = current_sheet(), cols, collapsed = FALSE,
 }
 
 #' @export
-#' @rdname wb_grouping
+#' @rdname workbook_grouping
 wb_ungroup_cols <- function(wb, sheet = current_sheet(), cols) {
   assert_workbook(wb)
   wb$clone()$ungroup_cols(sheet = sheet, cols = cols)
 }
 
 
 #' @export
-#' @rdname wb_grouping
+#' @rdname workbook_grouping
 #' @examples
 #' ### create grouping levels
 #' grp_rows <- list(
@@ -2182,7 +2181,7 @@ wb_group_rows <- function(wb, sheet = current_sheet(), rows, collapsed = FALSE,
 }
 
 #' @export
-#' @rdname wb_grouping
+#' @rdname workbook_grouping
 wb_ungroup_rows <- function(wb, sheet = current_sheet(), rows) {
   assert_workbook(wb)
   wb$clone()$ungroup_rows(sheet = sheet, rows = rows)

R/read.R

@@ -1,94 +1,117 @@
+# `wb_to_df()` ----------------------------------------
 #' Create Dataframe from Workbook
 #'
-#' Simple function to create a dataframe from a workbook. Simple as in simply
+#' Simple function to create a `data.frame` from a workbook. Simple as in simply
 #' written down. [read_xlsx()] and [wb_read()] are just internal wrappers for
 #' [wb_to_df()] intended for people coming from other packages.
 #'
+#' @details
+#' Depending if the R package `hms` is loaded, `wb_to_df()` returns
+#' `hms` variables or string variables in the `hh:mm:ss` format.
+#'
+#' The `types` argument must be a named numeric.
+#' * 0: character
+#' * 1: numeric
+#' * 2: date
+#' * 3: posixt
+#' * 4: logical
+#' @seealso [wb_get_named_regions()]
+#'
 #' @param file An xlsx file, Workbook object or URL to xlsx file.
 #' @param sheet Either sheet name or index. When missing the first sheet in the workbook is selected.
-#' @param col_names If TRUE, the first row of data will be used as column names.
-#' @param row_names If TRUE, the first col of data will be used as row names.
+#' @param col_names If `TRUE`, the first row of data will be used as column names.
+#' @param row_names If `TRUE`, the first col of data will be used as row names.
 #' @param dims Character string of type "A1:B2" as optional dimensions to be imported.
-#' @param detect_dates If TRUE, attempt to recognize dates and perform conversion.
-#' @param show_formula If TRUE, the underlying Excel formulas are shown.
-#' @param convert If TRUE, a conversion to dates and numerics is attempted.
-#' @param skip_empty_cols If TRUE, empty columns are skipped.
-#' @param skip_empty_rows If TRUE, empty rows are skipped.
-#' @param skip_hidden_cols If TRUE, hidden columns are skipped.
-#' @param skip_hidden_rows If TRUE, hidden rows are skipped.
+#' @param detect_dates If `TRUE`, attempt to recognize dates and perform conversion.
+#' @param show_formula If `TRUE`, the underlying Excel formulas are shown.
+#' @param convert If `TRUE`, a conversion to dates and numerics is attempted.
+#' @param skip_empty_cols If `TRUE`, empty columns are skipped.
+#' @param skip_empty_rows If `TRUE`, empty rows are skipped.
+#' @param skip_hidden_cols If `TRUE`, hidden columns are skipped.
+#' @param skip_hidden_rows If `TRUE`, hidden rows are skipped.
 #' @param start_row first row to begin looking for data.
 #' @param start_col first column to begin looking for data.
-#' @param rows A numeric vector specifying which rows in the Excel file to read. If NULL, all rows are read.
-#' @param cols A numeric vector specifying which columns in the Excel file to read. If NULL, all columns are read.
-#' @param named_region Character string with a named_region (defined name or table). If no sheet is selected, the first appearance will be selected.
-#' @param types A named numeric indicating, the type of the data. 0: character, 1: numeric, 2: date, 3: posixt, 4:logical. Names must match the returned data
-#' @param na.strings A character vector of strings which are to be interpreted as NA. Blank cells will be returned as NA.
-#' @param na.numbers A numeric vector of digits which are to be interpreted as NA. Blank cells will be returned as NA.
-#' @param fill_merged_cells If TRUE, the value in a merged cell is given to all cells within the merge.
-#' @param keep_attributes If TRUE additional attributes are returned. (These are used internally to define a cell type.)
+#' @param rows A numeric vector specifying which rows in the Excel file to read.
+#'   If `NULL`, all rows are read.
+#' @param cols A numeric vector specifying which columns in the Excel file to read.
+#'   If `NULL`, all columns are read.
+#' @param named_region Character string with a `named_region` (defined name or table).
+#'   If no sheet is selected, the first appearance will be selected.
+#' @param types A named numeric indicating, the type of the data.
+#'   Names must match the returned data. See **Details** for more.
+#' @param na.strings A character vector of strings which are to be interpreted as `NA`.
+#'   Blank cells will be returned as `NA`.
+#' @param na.numbers A numeric vector of digits which are to be interpreted as `NA`.
+#'   Blank cells will be returned as `NA`.
+#' @param fill_merged_cells If `TRUE`, the value in a merged cell is given to all cells within the merge.
+#' @param keep_attributes If `TRUE` additional attributes are returned.
+#'   (These are used internally to define a cell type.)
 #' @param ... additional arguments
-#' @details
-#' Depending if the R package `hms` is loaded, `wb_to_df()` returns `hms` variables or string variables in the `hh:mm:ss` format.
-#' @examples
 #'
-#'   ###########################################################################
-#'   # numerics, dates, missings, bool and string
-#'   xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")
-#'   wb1 <- wb_load(xlsxFile)
+#' @examples
+#' ###########################################################################
+#' # numerics, dates, missings, bool and string
+#' example_file <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")
+#' wb1 <- wb_load(example_file)
 #'
-#'   # import workbook
-#'   wb_to_df(wb1)
+#' # import workbook
+#' wb_to_df(wb1)
 #'
-#'   # do not convert first row to colNames
-#'   wb_to_df(wb1, colNames = FALSE)
+#' # do not convert first row to column names
+#' wb_to_df(wb1, col_names = FALSE)
 #'
-#'   # do not try to identify dates in the data
-#'   wb_to_df(wb1, detectDates = FALSE)
+#' # do not try to identify dates in the data
+#' wb_to_df(wb1, detect_dates = FALSE)
 #'
-#'   # return the underlying Excel formula instead of their values
-#'   wb_to_df(wb1, showFormula = TRUE)
+#' # return the underlying Excel formula instead of their values
+#' wb_to_df(wb1, show_formula = TRUE)
 #'
-#'   # read dimension without colNames
-#'   wb_to_df(wb1, dims = "A2:C5", colNames = FALSE)
+#' # read dimension without colNames
+#' wb_to_df(wb1, dims = "A2:C5", col_names = FALSE)
 #'
-#'   # read selected cols
-#'   wb_to_df(wb1, cols = c("A:B", "G"))
+#' # read selected cols
+#' wb_to_df(wb1, cols = c("A:B", "G"))
 #'
-#'   # read selected rows
-#'   wb_to_df(wb1, rows = c(2, 4, 6))
+#' # read selected rows
+#' wb_to_df(wb1, rows = c(2, 4, 6))
 #'
-#'   # convert characters to numerics and date (logical too?)
-#'   wb_to_df(wb1, convert = FALSE)
+#' # convert characters to numerics and date (logical too?)
+#' wb_to_df(wb1, convert = FALSE)
 #'
-#'   # erase empty rows from dataset
-#'   wb_to_df(wb1, skipEmptyRows = TRUE)
+#' # erase empty rows from dataset
+#' wb_to_df(wb1, skip_empty_rows = TRUE)
 #'
-#'   # erase empty columns from dataset
-#'   wb_to_df(wb1, skipEmptyCols = TRUE)
+#' # erase empty columns from dataset
+#' wb_to_df(wb1, skip_empty_cols = TRUE)
 #'
-#'   # convert first row to rownames
-#'   wb_to_df(wb1, sheet = 2, dims = "C6:G9", rowNames = TRUE)
+#' # convert first row to rownames
+#' wb_to_df(wb1, sheet = 2, dims = "C6:G9", row_names = TRUE)
 #'
-#'   # define type of the data.frame
-#'   wb_to_df(wb1, cols = c(2, 5), types = c("Var1" = 0, "Var3" = 1))
+#' # define type of the data.frame
+#' wb_to_df(wb1, cols = c(2, 5), types = c("Var1" = 0, "Var3" = 1))
 #'
-#'   # start in row 5
-#'   wb_to_df(wb1, startRow = 5, colNames = FALSE)
+#' # start in row 5
+#' wb_to_df(wb1, start_row = 5, col_names = FALSE)
 #'
-#'   # na string
-#'   wb_to_df(wb1, na.strings = "a")
+#' # na string
+#' wb_to_df(wb1, na.strings = "a")
 #'
-#'   ###########################################################################
-#'   # named_region // namedRegion
-#'   xlsxFile <- system.file("extdata", "namedRegions3.xlsx", package = "openxlsx2")
-#'   wb2 <- wb_load(xlsxFile)
+#' ###########################################################################
+#' # named_region // namedRegion
+#' file_named_region <- system.file("extdata", "namedRegions3.xlsx", package = "openxlsx2")
+#' wb2 <- wb_load(file_named_region)
 #'
-#'   # read dataset with named_region (returns global first)
-#'   wb_to_df(wb2, named_region = "MyRange", colNames = FALSE)
+#' # read dataset with named_region (returns global first)
+#' wb_to_df(wb2, named_region = "MyRange", col_names = FALSE)
 #'
-#'   # read named_region from sheet
-#'   wb_to_df(wb2, named_region = "MyRange", sheet = 4, colNames = FALSE)
+#' # read named_region from sheet
+#' wb_to_df(wb2, named_region = "MyRange", sheet = 4, col_names = FALSE)
 #'
+#' # read_xlsx() and wb_read()
+#' example_file <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")
+#' read_xlsx(file = example_file)
+#' df1 <- wb_read(file = example_file, sheet = 1)
+#' df2 <- wb_read(file = example_file, sheet = 1, rows = c(1, 3, 5), cols = 1:3)
 #' @export
 wb_to_df <- function(
     file,
@@ -571,19 +594,14 @@ wb_to_df <- function(
 }
 
 # `read_xlsx()` -----------------------------------------------------------------
-#' Read from an Excel file or Workbook object
+# Ignored by roxygen2 when combining documentation
+# #' Read from an Excel file or Workbook object
 #'
 #' @details
-#' Formulae written using write_formula to a Workbook object will not get picked up by read_xlsx().
+#' Formulae written using write_formula to a Workbook object will not get picked up by `read_xlsx()`.
 #' This is because only the formula is written and left to be evaluated when the file is opened in Excel.
 #' Opening, saving and closing the file with Excel will resolve this.
 #' @rdname wb_to_df
-#'
-#' @examples
-#'   # read_xlsx
-#'   xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")
-#'   read_xlsx(file = xlsxFile)
-#'
 #' @export
 read_xlsx <- function(
   file,
@@ -634,14 +652,6 @@ read_xlsx <- function(
 
 # `wb_read()` ------------------------------------------------------------------
 #' @rdname wb_to_df
-#' @examples
-#'   # wb_read
-#'   xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")
-#'   df1 <- wb_read(file = xlsxFile, sheet = 1)
-#'
-#'   xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")
-#'   df1 <- wb_read(file = xlsxFile, sheet = 1, rows = c(1, 3, 5), cols = 1:3)
-#' @seealso [wb_get_named_regions()]
 #' @export
 wb_read <- function(
   file,