Update dataset deprecation guidelines (#121)

deprecation.Rmd

@@ -110,51 +110,92 @@ Leave the man page from the previous step in place so that
 
 still shows the list of defunct functions and their appropriate replacements.
 
-## How To Deprecate A Package Dataset {#deprecate-dataset}
+## How To Deprecate An S3 Dataset {#deprecate-dataset}
 
-### Step 1 - Save a promise object
+### Step 1 - Create an S3 deprecation class 
 
-The initial step of deprecating a dataset is to signal to any users on
-the devel branch of Bioconductor that the dataset will no longer be used.
-This can be done using a `warning` message when the devel user loads
-the dataset. In order to do this, we first create a promise object with
-the same name as the dataset name using the `delayedAssign` function:
+The initial step of deprecating a dataset is to signal to users that the
+dataset will no longer be used. Alert the user with a `warning` message added to
+its `print` method. To do this, first add the deprecation class to the dataset
+object. Note that the class name here is arbitrary but it should be descriptive:
 
-    delayedAssign(
-        x = "pkgDataset",
-        value = {
-            warning("'pkgDataset' dataset is deprecated; see '?newData'")
-            pkgDataset
-        }
-    )
+    class(pkgDataset) <- c("DeprecatedData", class(pkgDataset))
 
-You can also include the dataset as an output after the warning.
-We then replace the original `.Rda` dataset file in the package with the
-promise object and dataset using the `save` function:
+Then serialize the class as an R object so that it can be loaded in the
+package:
 
-    save("pkgDataset", eval.promises = FALSE, file = "data/pkgDataset.Rda")
+    save(pkgDataset, file = "data/pkgDataset.rda")
 
-With the `eval.promises` argument set to `FALSE`, we can delay the evaluation
-of the promise object until the user loads the data with
-`data("pkgDataset", package = "yourPkg")`. The user will then get a warning
-along with the dataset. The warning should include instructions that will point
-the user to a new dataset or functionality that will replace the data, if
-necessary.
+or with `usethis`:
 
-### Step 2 - Update documentation
+    usethis::use_data(pkgDataset, overwrite = TRUE)
 
-After the promise object has been saved, we update the documentation to
+### Step 2 - Create a print method
+
+Then create a print method for the new class that will print the warning
+message:
+
+    print.DeprecatedData <- function(x, ...) {
+        warning("'pkgDataset' dataset is deprecated; see '?newData'")
+        NextMethod()
+    }
+
+It is useful to guide the user to the replacement dataset or functionality
+that will replace the data in the `warning` message. Note that this method
+should be exported in the package's `NAMESPACE` file.
+
+### Step 3 - Update documentation
+
+After the dataset object has been saved, we update the documentation to
 reflect the changes and provide additional details and resources for
 users as necessary. It is recommended to include a "&#91;Deprecated&#93;" label
 in the data documentation title.
 
-### Step 3 - Defunct the dataset
+### Step 4 - Defunct the dataset
+
+In the following release cycle, upgrade the warning message to an error
+message to indicate that it is no longer available. The data can then be
+removed from the package. Remember to update the "&#91;Deprecated&#93;"
+label in the documentation title to "&#91;Defunct&#93;".
+
+## How to Deprecate An S4 Dataset
+
+### Step 1 - Create an S4 deprecation class
+
+With S4, the process is similar to S3, but we need to create a new class
+that inherits from the original class with `setClass`. The class name here
+is arbitrary but should be descriptive:
+
+    .DeprecatedData <-
+        setClass("DeprecatedData", contains = "S4Class")
+
+The `setClass` call creates a generator function which we can then use
+to create an instance of the new class from the old object:
+
+    myS4DataObject <- .DeprecatedData(myS4DataObject)
+
+We then serialize the object to disk so that it can be loaded in the
+package: 
+
+    save(myS4DataObject, file = "data/myS4DataObject.rda")
+
+or by using `usethis`:
+
+    usethis::use_data(myS4DataObject, overwrite = TRUE)
+
+### Step 2 - Create a show method
+
+Create a `show` method for the new class that will produce a warning message:
+
+    setMethod("show", "DeprecatedData", function(object) {
+        warning("This dataset is deprecated; see '?newData'")
+        callNextMethod()
+    })
+
+Note that this method should be exported in the package's `NAMESPACE` and
+the `show` generic should be imported from the `methods` package.
 
-In the following release cycle, you can update the warning message to indicate
-that the dataset is defunct and remove it entirely from the promise object
-i.e., from the expression in the `delayedAssign` function. We can also update
-the "&#91;Deprecated&#93;" label in the documentation title to
-"&#91;Defunct&#93;".
+Note that steps 3 and 4 are the same as for S3 datasets.
 
 ## How to Deprecate a Package {#deprecate-package}