fix deprecation message; add renaming to the examples (#362)

before:
```
r$> lifecycle::deprecate_soft("0.6.1", "datanames()", details = "names()")
Warning message:
`datanames()` was deprecated in <NA> 0.6.1.
ℹ names()
```

after:
```
r$> lifecycle::deprecate_soft("0.6.1", "datanames()", with = "names()")
Warning message:
`datanames()` was deprecated in <NA> 0.6.1.
ℹ Please use `names()` instead.
```

Also updated docs to give example of reassigning names - previously done
with `datanames(x) <- ...` which is deprecated now

R/deprecated.R

@@ -19,16 +19,20 @@
 #' @rdname datanames
 #' @export
 datanames <- function(x) {
-  lifecycle::deprecate_soft("0.6.1", "datanames()", details = "names()")
+  lifecycle::deprecate_soft(
+    when = "0.6.1",
+    what = "datanames()",
+    with = "names()"
+  )
   names(x)
 }
 
 #' @rdname datanames
 #' @export
 `datanames<-` <- function(x, value) {
   lifecycle::deprecate_soft(
-    "0.6.1",
-    "`datanames<-`()",
+    when = "0.6.1",
+    what = "`datanames<-`()",
     details = "invalid to use `datanames()<-` or `names()<-` on an object of class `teal_data`. See ?names.teal_data"
   )
   x
@@ -39,8 +43,8 @@ datanames <- function(x) {
 #' @keywords internal
 `names<-.teal_data` <- function(x, value) {
   lifecycle::deprecate_warn(
-    "0.6.1",
-    "`names<-.teal_data`()",
+    when = "0.6.1",
+    what = "`names<-.teal_data`()",
     details = "invalid to use `datanames()<-` or `names()<-` on an object of class `teal_data`. See ?names.teal_data"
   )
   x

R/teal_data-names.R

@@ -7,6 +7,8 @@
 #' To get the names of all objects, use `ls(x, all.names = TRUE)`, however, it
 #' will not group the names by the join_keys topological structure.
 #'
+#' In order to rename objects in the `teal_data` object, use base R functions (see examples).
+#'
 #' @param x A (`teal_data`) object to access or modify.
 #'
 #' @return A character vector of names.
@@ -16,9 +18,18 @@
 #' td <- within(td, mtcars <- mtcars)
 #' names(td)
 #'
+#' # hidden objects with dot-prefix
 #' td <- within(td, .CO2 <- CO2)
 #' names(td) # '.CO2' will not be returned
 #'
+#' # rename objects
+#' td <- teal_data(iris = iris)
+#' td <- within(td, {
+#'   new_iris <- iris
+#'   rm(iris)
+#' })
+#' names(td) # only 'new_iris' will be returned
+#'
 #' @export
 names.teal_data <- function(x) {
   # Sorting from `ls` can be safely done as environments don't have any order