internal: use wb_comment() in wb_add_thread + deprecations guide

NEWS.md

@@ -9,7 +9,7 @@
 
 ## Deprecated functions
 
-These functions are no longer recommended.
+These functions are no longer recommended. A [guide](https://janmarvin.github.io/openxlsx2/dev/reference/openxlsx2-deprecated.html) was created to help users 
 They will continue to work for some time, but changing to newer functions is recommended.
 
 * `delete_data()` is deprecated in favour of `wb_remove_tables()` or `wb_clean_sheet()`

R/class-comment.R

@@ -77,9 +77,7 @@ wbComment <- R6::R6Class(
 )
 # Comment creation wrappers ----------------------------------------------------------------
 
-# TODO create_comment() should leverage wbComment$new() more
-# TODO write_comment() should leverage wbWorkbook$addComment() more
-# TODO remove_comment() should leverage wbWorkbook$remove_comment() more
+# TODO wb_comment() should leverage wbComment$new() more
 
 #' Create a comment object
 #'
@@ -167,7 +165,7 @@ wb_comment <- function(text = NULL,
 
 #' Create a comment
 #'
-#' Use [wb_comment()] in new code.
+#' Use [wb_comment()] in new code. See [openxlsx2-deprecated]
 #'
 #' @inheritParams wb_comment
 #' @param author A string, by default, will use "user"
@@ -183,26 +181,26 @@ create_comment <- function(text,
   height = 4) {
   #
   if (getOption("openxlsx2.soon_deprecated", default = FALSE)) {
-    .Deprecated("wb_comment()")
+    .Deprecated("wb_comment()", old = "create_comment()")
   }
   wb_comment(text = text, author = author, style = style, visible = visible, width = width[1], height = height[1])
 }
 
 #' Internal comment functions
 #'
-#' Users are advised to use [wb_add_comment()] and [wb_remove_comment()]
+#' Users are advised to use [wb_add_comment()] and [wb_remove_comment()].
+#' This function is used internally by openxlsx2. It will stop exporting it at
+#' some point in the future. Use the replacement function at your earliest convenience.
 #' @name comment_internal
 NULL
 
 #' @rdname comment_internal
-#' @param wb A workbook object
-#' @param sheet A vector of names or indices of worksheets
-#' @param col Column a column number of letter. For `remove_comment` this can be a range.
-#' @param row A row number. For `remove_comment` this can be a range.
-#' @param comment A Comment object. See [create_comment()].
-#' @param dims worksheet cell "A1"
+#' @inheritParams wb_add_comment
+#' @param comment An object created by [create_comment()]
+#' @param row,col Row and column of the cell
 #' @keywords internal
 #' @export
+#' @inherit wb_add_comment examples
 write_comment <- function(
     wb,
     sheet,

R/class-workbook-wrappers.R

@@ -3118,7 +3118,8 @@ wb_add_thread <- function(
     reply     = FALSE,
     resolve   = FALSE
 ) {
-
+  # wb_add_thread now uses wb_comment internally. No change detected.
+  # means that add_thread does not look at visibility. (I think it's fine.)
   if (missing(person_id)) {
     person_id <- substitute()
   }

R/class-workbook.R

@@ -3828,7 +3828,7 @@ wbWorkbook <- R6::R6Class(
       if (length(cmt <- wb_cmt$comment)) {
         # TODO not sure yet what to do
       } else {
-        cmt <- create_comment(text = comment, author = "")
+        cmt <- wb_comment(text = comment, author = "")
         self$add_comment(sheet = sheet, dims = dims, comment = cmt)
       }
       wb_cmt <- wb_get_comment(self, sheet, dims)

R/openxlsx2-package.R

@@ -106,14 +106,67 @@ openxlsx2_celltype <- c(
   hms_time       = 15
 )
 
-#' Deprecated Functions in Package *openxlsx2*
+#' Deprecated functions in package *openxlsx2*
 #'
-#' These functions are provided for compatibility with older versions of `openxlsx2`, and may be defunct as soon as the next release.
-#' @details
+#' @description
+#' These functions are provided for compatibility with older versions of `openxlsx2`,
+#' and may be defunct as soon as the next release. This guide helps you update your
+#' code to the latest standards.
+#'
+#' As of openxlsx2 v1.0, API change should be minimal.
+#'
+#' # Internal functions
+#'
+#' These functions are used internally by openxlsx2. It is no longer advertised
+#' to use them in scripts. They originate from openxlsx, but do not fit openxlsx2's API.
+#'
+#' You should be able to modify
+#' * [delete_data()] -> [wb_clean_sheet()]
+#' * [write_comment()] -> [wb_add_comment()]
+#' * [remove_comment()] -> [wb_remove_comment()]
+#' * [write_formula()] -> [wb_add_formula()]
+#'
+#' You should be able to change those with minimal changes
+#'
+#' # Deprecated functions
+#'
+#' First of all, you can set an option that will add warnings when using deprecated
+#' functions.
+#'
+#' ```
+#' options("openxlsx2.soon_deprecated" = TRUE)
+#' ```
+#'
+#' # Argument changes
+#'
+#' For consistency, arguments were renamed to snake_case for the 0.8 release.
+#' It is now recommended to use `dims` (the cell range) in favour of `row`, `col`, `start_row`, `start_col`
+#'
+#' See [wb_dims()] as it provides many options on how to provide cell range
+#'
+#' # Functions with a new name
+#'
+#' These functions were renamed for consistency.
 #' * [convertToExcelDate()] -> [convert_to_excel_date()]
 #' * [wb_grid_lines()] -> [wb_set_grid_lines()]
-#' * [delete_data()] -> [wb_clean_sheet()]
 #' * [create_comment()] -> [wb_comment()]
+#'
+#'
+#' # Deprecated usage
+#'
+#' * `wb_get_named_regions()` will no longer allow providing a file.
+#'
+#' ```
+#' ## Before
+#' wb_get_named_regions(file)
+#'
+#' ## Now
+#' wb <- wb_load(file)
+#' wb_get_named_regions(wb)
+#' # also possible
+#' wb_load(file)$get_named_regions()`
+#' ```
+#'
 #' @seealso [.Deprecated]
 #' @name openxlsx2-deprecated
 NULL

R/utils.R

@@ -70,7 +70,7 @@ temp_dir <- function(pattern = "file") {
   tmpDir
 }
 
-openxlsx2_options <- function() {
+default_save_opt <- function() {
   options(
     # increase scipen to avoid writing in scientific
     scipen = 200,

R/write.R

@@ -728,7 +728,7 @@ write_data_table <- function(
   # force with globalenv() options
   x <- force(x)
 
-  op <- openxlsx2_options()
+  op <- default_save_opt()
   on.exit(options(op), add = TRUE)
 
   if (!is.null(dims)) {