improve deprecate/defunct (issue 1420)

brianstock · Jun 3, 2018 · 24d2014 · 24d2014
1 parent 8f31c40
commit 24d2014
Show file tree

Hide file tree

Showing 22 changed files with 1,414 additions and 913 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -149,7 +149,6 @@ export(abbreviateTimeLabels,
        lowpass,
        magneticField,
        makeFilter,
-       makeSection,
        mapArrows,
        mapAxis,
        mapContour,
@@ -208,7 +207,7 @@ export(abbreviateTimeLabels,
        oce.debug, oceDebug,
        oce.edit, oceEdit,
        oce.filter, oceFilter,
-       oce.magic, oceMagic,
+       oceMagic,
        oce.convolve, oceConvolve,
        oce.contour, oceContour,
        oce.grid,

diff --git a/NEWS b/NEWS
@@ -1,4 +1,8 @@
 0.9-24
+- remove makeSection()
+- make defunct: addColumn byteToBinary ctdAddColumn ctdUpdateHeader findInOrdered
+- make defunct: mapZones mapMeridians oce.as.POSIXlt oce.magic
+- byteToBinary(., endian="little") designated as defunct
 - as.tidem() added
 - read.odf() handles multiple NULL_VALUEs
 - flag improvements

diff --git a/R/ctd.R b/R/ctd.R
@@ -1411,9 +1411,10 @@ as.ctd <- function(salinity, temperature=NULL, pressure=NULL, conductivity=NULL,
 }
 
 
-#' Add a Column to the Data Slot of a CTD Object [deprecated]
+#' Add a Column to the Data Slot of a CTD Object [defunct]
+#'
+#' \strong{WARNING:} This function will be removed soon; see \link{oce-defunct}.
 #'
-#' \strong{WARNING:} This function will be removed soon; see \link{oce-deprecated}.
 #' Use \code{\link{oceSetData}} instead of the present function.
 #'
 #' Add a column to the \code{data} slot of an object of
@@ -1443,21 +1444,14 @@ as.ctd <- function(salinity, temperature=NULL, pressure=NULL, conductivity=NULL,
 #' @seealso The documentation for \code{\link{ctd-class}} explains the structure
 #'    of CTD objects, and also outlines the other functions dealing with them.
 #'
-#' @examples
-#' library(oce)
-#' data(ctd)
-#' F <- 32 + (9/5)*ctd[["temperature"]]
-#' ctdNew <- ctdAddColumn(ctd, F, "temperatureF",
-#'     unit=list(unit=expression(degree*F), scale="ITS-90"))
-#'
 #' @author Dan Kelley
 #'
 #' @family functions that will be removed soon
 ctdAddColumn <- function (x, column, name, label, unit=NULL, log=TRUE, originalName="",
                           debug=getOption("oceDebug"))
 {
-    .Deprecated("oceSetData",
-                msg="ctdAddColume() will be removed soon. Use oceSetData() instead. See ?'oce-deprecated'.")
+    .Defunct("oceSetData",
+             msg="ctdAddColumn() is disallowed and will be removed soon. Use oceSetData() instead. See ?'oce-defunct'.")
     ## FIXME: not using the units
     oceDebug(debug, "ctdAddColumn(x, column, name=\"", name, "\", label=\"", label, "\", debug) {\n", sep="", unindent=1)
     if (missing(column))
@@ -2507,9 +2501,9 @@ ctdTrim <- function(x, method, removeDepthInversions=FALSE, parameters=NULL,
 }
 
 
-#' Update a CTD Header [deprecated]
+#' Update a CTD Header [defunct]
 #'
-#' \strong{WARNING:} This function will be removed soon; see \link{oce-deprecated}.
+#' \strong{WARNING:} This function will be removed soon; see \link{oce-defunct}.
 #'
 #' Update the header of a \code{ctd} object, e.g. adjusting \code{nvalues} and the
 #' \code{span} of each column. This is done automatically by \code{ctdTrim}, for
@@ -2521,12 +2515,6 @@ ctdTrim <- function(x, method, removeDepthInversions=FALSE, parameters=NULL,
 #'
 #' @return A new \code{\link{ctd-class}} object.
 #'
-#' @examples
-#' library(oce)
-#' data(ctd)
-#' ctd[["pressure"]] <- ctd[["pressure"]] + 3
-#' ctdNew <- ctdUpdateHeader(ctd)
-#'
 #' @references
 #' The Seabird CTD instrument is described at
 #'   \code{http://www.seabird.com/products/spec_sheets/19plusdata.htm}.
@@ -2536,8 +2524,8 @@ ctdTrim <- function(x, method, removeDepthInversions=FALSE, parameters=NULL,
 #' @family functions that will be removed soon
 ctdUpdateHeader <- function (x, debug=FALSE)
 {
-    .Deprecated("oceSetMetadata",
-                msg="ctdUpdateHeader() will be removed soon. See ?'oce-deprecated'.")
+    .Defunct("oceSetMetadata",
+             msg="ctdUpdateHeader() is disallowed and will be removed soon. See ?'oce-defunct'.")
     if (length(x@metadata$header) < 1)
         stop("there is no header in this CTD object")
     if (length(x@data) < 1)

diff --git a/R/map.R b/R/map.R
@@ -1819,7 +1819,7 @@ mapGrid <- function(dlongitude=15, dlatitude=15, longitude, latitude,
 }
 
 
-#' Add Meridians on a Map [deprecated]
+#' Add Meridians on a Map [defunct]
 #'
 #' \strong{WARNING:} This function will be removed soon; see \link{oce-deprecated}.
 #' Use \code{\link{mapGrid}} instead of the present function.
@@ -1845,8 +1845,8 @@ mapGrid <- function(dlongitude=15, dlatitude=15, longitude, latitude,
 #' @family functions that will be removed soon
 mapMeridians <- function(latitude, lty='solid', lwd=0.5*par('lwd'), col='darkgray', ...)
 {
-    .Deprecated("mapGrid",
-                msg="mapMeridians() will be removed soon; use mapGrid() instead. See ?'oce-deprecated'.")
+    .Defunct("mapGrid",
+             msg="mapMeridians() will be removed soon. Use mapGrid() instead. See ?'oce-defunct'.")
     if ("none" == .Projection()$type)
         stop("must create a map first, with mapPlot()\n")
     warning("Use mapGrid(longitude=NULL,latitude=latitude) instead of mapMeridians(latitude)")
@@ -2108,7 +2108,7 @@ mapTissot <- function(grid=rep(15, 2), scale=0.2, crosshairs=FALSE, ...)
 }
 
 
-#' Add Zones to a Map [deprecated]
+#' Add Zones to a Map [defunct]
 #'
 #' \strong{WARNING:} This function will be removed soon; see \link{oce-deprecated}.
 #'
@@ -2138,8 +2138,8 @@ mapTissot <- function(grid=rep(15, 2), scale=0.2, crosshairs=FALSE, ...)
 #' @family functions that will be removed soon
 mapZones <- function(longitude, polarCircle=0, lty='solid', lwd=0.5*par('lwd'), col='darkgray', ...)
 {
-    .Deprecated("mapGrid",
-                msg="mapZones() will be removed soon; use mapGrid() instead. See ?'oce-deprecated'.")
+    .Defunct("mapGrid",
+             msg="mapZones() will be removed soon. Use mapGrid() instead. See ?'oce-defunct'.")
     if ("none" == .Projection()$type)
         stop("must create a map first, with mapPlot()\n")
     warning("Use mapGrid(longitude=longitude,latitude=NULL) instead of mapZones(longitude)")

diff --git a/R/misc.R b/R/misc.R
@@ -13,9 +13,10 @@ abbreviateVector <- function(x)
 }
 
 
-#' Add a Column to the Data Slot of an Oce object [deprecated]
+#' Add a Column to the Data Slot of an Oce object [defunct]
+#'
+#' \strong{WARNING:} This function will be removed soon; see \link{oce-defunct}.
 #'
-#' \strong{WARNING:} This function will be removed soon; see \link{oce-deprecated}.
 #' Use \code{\link{oceSetData}} instead of the present function.
 #'
 #' @param x A \code{ctd} object, e.g. as read by \code{\link{read.ctd}}.
@@ -29,8 +30,8 @@ abbreviateVector <- function(x)
 #' @family functions that will be removed soon
 addColumn <- function (x, data, name)
 {
-    .Deprecated("oceSetData",
-                msg="addColumn() will be removed soon; use oceSetData() instead. See ?'oce-deprecated'.")
+    .Defunct("oceSetData",
+             msg="addColumn() is disallowed and will be removed soon. Use oceSetData() instead. See ?'oce-defunct'.")
     if (!inherits(x, "oce"))
         stop("method is only for oce objects")
     if (missing(data))
@@ -1234,31 +1235,18 @@ errorbars <- function(x, y, xe, ye, percent=FALSE, style=0, length=0.025, ...)
 }
 
 
-#' Find indices of times in an ordered vector [deprecated]
-#'
-#' \strong{WARNING:} This function will be removed soon;
-#' see \link{oce-deprecated}.  The replacement is trivial:
-#' just change a call like e.g. \code{findInOrdered(x,f)}
-#' to \code{\link{findInterval}(f,x)} (which is what the function
-#' started doing, on 2017-09-07, after a major bug was found).
+#' Find indices of times in an ordered vector [defunct]
 #'
-#' The indices point to the largest items in \code{x} that are less than or
-#' equal the values in \code{f}.  This works by simply calling
-#' \code{\link{findInterval}(x=f, vec=x)}, and users are probably
-#' better off using \code{\link{findInterval}} directly.
+#' \strong{WARNING:} This function will be removed soon; see \link{oce-defunct}.
 #'
-#' @param x a numeric vector, in increasing order by value.
-#' @param f a numeric vector of items whose indices are sought.
-#' @return A numerical vector indicating the indices of left-sided neighbors.
+#' @param x Ignored, since this function is defunct.
+#' @param f Ignored, since this function is defunct.
 #' @author Dan Kelley
-#' @examples
-#'
-#' findInOrdered(seq(0, 10, 1), c(1.2, 7.3))
+#' @family functions that will be removed soon
 findInOrdered <- function(x, f)
 {
-    .Deprecated("mapGrid",
-                msg="findInOrdered(f,x) will be removed soon; use findInterval(f,x) instead. See ?'oce-deprecated'.")
-    findInterval(f, x)
+    .Defunct("findInterval",
+             msg="findInOrdered() is disallowed and will be removed soon. Use findInterval() instead. See ?'oce-defunct'.")
 }
 
 
@@ -3608,10 +3596,10 @@ bcdToInteger <- function(x, endian=c("little", "big"))
 }
 
 
-#' Format bytes as binary
+#' Format bytes as binary [defunct]
 #'
 #' \strong{WARNING:} The \code{endian} argument will soon be removed
-#' from this function; see \link{oce-deprecated}.
+#' from this function; see \link{oce-defunct}.
 #' This is because the actions for \code{endian="little"} made
 #' no sense in practical work. The default value for \code{endian}
 #' was changed to \code{"big"} on 2017 May 6.
@@ -3631,15 +3619,13 @@ bcdToInteger <- function(x, endian=c("little", "big"))
 #' library(oce)
 #' ## Note comparison with rawToBits():
 #' a <- as.raw(0x0a)
-#' byteToBinary(a, "big") # "00001010"
-#' rev(rawToBits(a))      # 00 00 00 00 01 00 01 00
-byteToBinary <- function(x, endian)
+#' byteToBinary(a, "big")        # "00001010"
+#' as.integer(rev(rawToBits(a))) # 0 0 0 0 1 0 1 0
+byteToBinary <- function(x, endian="big")
 {
-    if (missing(endian))
-        endian <- "big"
     if (endian != "big")
-        .Deprecated("rawToBits",
-                    msg="byteToBinary(): the endian=\"little\" argument will be disallowed soon; see ?'oce-deprecated'.")
+        .Defunct("rawToBits",
+                 msg="byteToBinary(.,'little') is disallowed and will be removed soon. See ?'oce-defunct'.")
     ## onebyte2binary <- function(x)
     ## {
     ##     c("0000", "0001", "0010", "0011",

diff --git a/R/oce.R b/R/oce.R
@@ -63,6 +63,9 @@
 NULL
 
 
+###################################################################################
+## IMPORTANT: Update this and test_deprecation, whenever function status changes. #
+###################################################################################
 #' Deprecated and Defunct Elements of package \sQuote{oce}
 #'
 #' Certain functions and function arguments are still provided for
@@ -80,32 +83,35 @@ NULL
 #'
 #' \tabular{lll}{
 #' \strong{Deprecated}       \tab \strong{Replacement}            \tab \strong{Notes}\cr
-#' \code{findInOrdered(x,f)} \tab \code{\link{findInterval}(f,x)} \tab Deprecated 2017-09-07\cr
-#' \code{mapZones}           \tab \code{\link{mapGrid}}           \tab Deprecated 2016-02-13\cr
-#' \code{mapMeridians}       \tab \code{\link{mapGrid}}           \tab Deprecated 2016-02-13\cr
-#' \code{addColumn}          \tab \code{\link{oceSetData}}        \tab Deprecated 2016-08-01\cr
-#' \code{oce.magic}          \tab \code{\link{oceMagic}}          \tab Deprecated 2016-09-01\cr
-#' \code{ctdAddColumn}       \tab \code{\link{oceSetData}}        \tab Deprecated 2016-11-11\cr
-#' \code{ctdUpdateHeader}    \tab -                               \tab Deprecated 2016-11-11\cr
-#' \code{oce.as.POSIXlt}     \tab \code{\link[lubridate]{parse_date_time}} \tab Deprecated 2016-12-17\cr
+#' \code{byteToBinary}       \tab \code{\link{rawToBits}}         \tab Deprecated in 2016?\cr
 #' }
 #'
 #' The following are marked "defunct", so calling them in the
 #' the present version produces an error message that hints at a replacement
 #' function. Once a function is marked "defunct" on one CRAN release, it will
 #' be slated for outright deletion in a subsequent release.
 #'
+## In table below, I put two spaces before version number, if a build-test exists.
 #'\tabular{lll}{
-#'\strong{Defunct}   \tab \strong{Replacement}     \tab \strong{Notes}\cr
-#'\code{makeSection} \tab \code{\link{as.section}} \tab Improve utility and name sensibility\cr
-#'\code{columns}     \tab \code{\link{read.ctd}}   \tab Unnecessary; never worked\cr
+#'\strong{Defunct}       \tab \strong{Replacement}                     \tab \strong{Version} \cr
+#'\code{addColumn}       \tab \code{\link{oceSetData}}                 \tab  0.9.24\cr
+#'\code{byteToBinary}    \tab \code{\link{rawToBits}}                  \tab  0.9.24 'endian="little" disallowed\cr
+#'\code{findInOrdered}   \tab \code{\link{findInterval}}               \tab  0.9.24\cr
+#'\code{ctdAddColumn}    \tab \code{\link{oceSetData}}                 \tab  0.9.24\cr
+#'\code{ctdUpdateHeader} \tab \code{\link{oceSetMetadata}}             \tab  0.9.24\cr
+#'\code{mapZones}        \tab \code{\link{mapGrid}}                    \tab  0.9.24\cr
+#'\code{mapMeridians}    \tab \code{\link{mapGrid}}                    \tab  0.9.24\cr
+#'\code{oce.as.POSIXlt}  \tab \code{\link[lubridate]{parse_date_time}} \tab  0.9.24\cr
+#'\code{oce.magic}       \tab \code{\link{oceMagic}}                   \tab  0.9.24\cr
 #'}
 #'
-#' The following were removed in recent years.
+#' The following were removed recently, having been marked as "deprecated"
+#' in at least one CRAN release, and thereafter as "defunct" in at least
+#' one CRAN release.
 #'
 #'\tabular{lll}{
-#'\strong{Function}  \tab \strong{Replacement}     \tab \strong{Notes}\cr
-#' FILL IN           \tab FILL IN                  \tab FILL IN
+#'\strong{Function}      \tab \strong{Replacement}         \tab \strong{Version}\cr
+#'\code{makeSection}     \tab \code{\link{as.section}}     \tab           0.9.24\cr
 #'}
 #'
 #' Several \sQuote{oce} function arguments are considered "deprecated", which
@@ -1239,9 +1245,10 @@ oce.plot.ts <- function(x, y, type="l", xlim, ylim, xlab, ylab,
 }
 
 
-#' Oce Variant of as.POSIXlt [deprecated]
+#' Oce Variant of as.POSIXlt [defunct]
 #'
 #' \strong{WARNING:} This function will be removed soon; see \link{oce-deprecated}.
+#'
 #' It was realized in December of 2016 that this function was not used within
 #' oce, and also that \code{\link[lubridate]{parse_date_time}} in the
 #' \CRANpkg{lubridate} package was superior and therefore a better choice for
@@ -1253,10 +1260,10 @@ oce.plot.ts <- function(x, y, type="l", xlim, ylim, xlab, ylab,
 #' @return A POSIXlt object.
 #' @author Dan Kelley
 #' @family functions that will be removed soon
-oce.as.POSIXlt <- function (x, tz = "")
+oce.as.POSIXlt <- function(x, tz = "")
 {
-    .Deprecated("lubridate::parse_date_time",
-                msg="oce.as.POSIXlt() will be removed soon; see ?'oce-deprecated'.")
+    .Defunct("lubridate::parse_date_time",
+             msg="oce.as.POSIXlt() will be removed soon. Use lubridate::parse_date_time() instead. See ?'oce-defunct'.")
     fromchar <- function(x)
     {
         xx <- x[1]
@@ -1543,10 +1550,8 @@ standardDepths <- function()
 #' within the file, the file name, or a combination of the two.
 #'
 #' \code{oceMagic} was previously called \code{oce.magic}, but that
-#' alias will be removed towards the end of the year 2016; see
-#' \link{oce-deprecated}.
+#' alias was removed in version 0.9.24; see \link{oce-defunct}.
 #'
-#' @aliases oceMagic oce.magic
 #' @param file a connection or a character string giving the name of the file
 #' to be checked.
 #' @param debug an integer, set non-zero to turn on debugging.  Higher values
@@ -1818,8 +1823,6 @@ oceMagic <- function(file, debug=getOption("oceDebug"))
     oceDebug(debug, "this is unknown\n")
     return("unknown")
 }
-oce.magic <- oceMagic
-