how to deprecate functions

Parent: Developer

From the users' point of view, oce uses the bioconductor system for removing functions. From the developers' point of view, the steps are as follows.

1. The developers come to an agreement on whether to remove the function. This decision is not taken lightly, and it can take days to make a decision. The main arguments in favour of removing a function are that (a) it is deficient in a way that is troublesome to users and that would be difficult to rectify, (b) oce offers a superior alternative, (c) the function is "stale," not having been used by the developers or (as signalled by issue reports) by users and (d) the function does not match a design pattern that is favoured in oce. Of these, the last is the weakest argument, although it is always considered carefully, because it helps to maintain the usability of oce, generally.

2. The function is "deprecated". This has three components.

   1. Its documentation is altered.

      1. The token [deprecated] is placed at the end of the title.
      2. A warning is put at the start of the description. It can help to use a form similar to that used in other functions within oce, e.g. the deprecation warning for oce.as.POSIXlt() reads: \strong{WARNING:} This function will be removed soon; see \link{oce-deprecated}. Use \code{\link[lubridate]{parse_date_time}} in the \CRANpkg{lubridate) package instead.
      3. The @family token that relates this to other functions is removed, as are other links to the function. (This is so that new users won't see discover it as easily.)
      4. a @family token about deprecation is inserted. This reads #' @family functions that will be removed soon (it must read exactly as shown, for the Roxygen parser to bind together the instances)

   2. A call to .Deprecated() is made at the start of the function. For example, the call used in oce.as.POSIXlt() reads as follows: .Deprecated("lubridate::parse_date_time",msg="oce.as.POSIXlt() will be removed soon; use lubridate::parse_date_time() instead. See ?'oce-deprecated'.")

   3. A note is added to the documentation item oce-deprecated (in R/oce.R). (This should include the date.)

3. After the next CRAN release, the source code moves to the "defunct" status. The steps are similar to the above; see the code for examples.