Are there best/recommended practices to follow when renaming functions in a new version of a package?

Question

I\'m updating an old package and shortening a bunch of really long function names. How do I let a user know the the old function has been deprecated? I document everything with

Answer 1

I guess the "right" answer depends on what you want. From my view:

1. The problem with Jeff's and Brandon's approach is that your index will list both function names and give no indication as to which is the preferred name. Moreover without some sort of .Deprecated call, the user is even more unlikely to know what the preferred way to call the function is.
2. The problem with Brian's approach was that the process for listing more than one function as deprecated was unclear to me.

So, enter my example below. In another location I define the 'good' versions of the functions (e.g. alchemy, latinSquareDigram). Here I define all of the old 'bad' versions that I want to produce deprecation warnings for. I followed the approach of the car package and changed all of my function calls for the deprecated version to use ... as the argument. This has helped me avoid a bunch of cluttered @param statements. I also have used the @name and @docType directives to make "yourPackageName-deprecated" appear in the index. Maybe somebody has a better way of doing this?

Now each of the deprecated functions still shows up in the index, but it says "Deprecated function(s) in the yourPackageName package" next to them and any calls to them produce a deprecation warning. To remove them from the index one could drop the @aliases directive, but then you would have user-level undocumented code objects which, I take it, is bad form.

#' Deprecated function(s) in the yourPackageName package
#' 
#' These functions are provided for compatibility with older version of
#' the yourPackageName package.  They may eventually be completely
#' removed.
#' @rdname yourPackageName-deprecated
#' @name yourPackageName-deprecated
#' @param ... Parameters to be passed to the modern version of the function
#' @docType package
#' @export  latinsquare.digram Conv3Dto2D Conv2Dto3D dist3D.l
#' @aliases latinsquare.digram Conv3Dto2D Conv2Dto3D dist3D.l
#' @section Details:
#' \tabular{rl}{
#'   \code{latinsquare.digram} \tab now a synonym for \code{\link{latinSquareDigram}}\cr
#'   \code{Conv3Dto2D} \tab now a synonym for \code{\link{conv3Dto2D}}\cr
#'   \code{Conv2Dto3D} \tab now a synonym for \code{\link{conv2Dto3D}}\cr
#'   \code{dist3D.l} \tab now a synonym for \code{\link{dist3D}}\cr
#' }
#'  
latinsquare.digram <- function(...) {
  .Deprecated("latinSquareDigram",package="yourPackageName")
  latinSquareDigram(...)
}
Conv3Dto2D <- function(...) {
  .Deprecated("conv3Dto2D",package="yourPackageName")
  conv3Dto2D(...)
}
Conv2Dto3D <- function(...) {
  .Deprecated("conv2Dto3D",package="yourPackageName")
  conv2Dto3D(...)
}
dist3D.l <- function(...) {
  .Deprecated("dist3D",package="yourPackageName")
  dist3D(...)
}
NULL