How to deprecate an argument?

I found this discussion when looking for a solution to rename a function argument for a function of a package. This is not exactly an answer to your question, but very familiar, and I thought maybe the solution is helpful for others as well.

So, to rename an argument of a function without harming existing function calls, I came up with the following solution, based on the answer from @John Smith.

The functionality of old_arg remains for deprecated function calls of foo and is ignored for function calls of the new version of foo.

# old version
foo <- function(x, y, old_arg = c("a", "b", "c")){

   old_arg <- match.arg(old_arg, c("a", "b", "c"))

   if(old_arg == "a"){
      return(x*y)
   }else if(old_arg == "b"){
      return(x+y)
   }else if(old_arg == "c"){
      return(x-y)
   }
}

# new version
foo <- function(x, y, new_arg = c("a", "b", "c"), old_arg = c("a", "b", "c")){

   if (!missing("old_arg")){
      warning("Argument deprecated, use new_arg instead. 
              The parameter new_arg is set equal the parameter old_arg.")
      new_arg <- old_arg
   }

   new_arg <- match.arg(new_arg, c("a", "b", "c"))
   if(new_arg == "a"){
      return(x*y)
   }else if(new_arg == "b"){
      return(x+y)
   }else if(new_arg == "c"){
      return(x-y)
   }
}

Something like as follows maybe would do for you?

foo <- function(paging = T, limit = 0) {
  if (!missing("paging"))
    warning("argument deprecated")
}

Example outputs:

# > foo()
# > foo(limit = 0)
# > foo(T)
# Warning message:
#   In foo(T) : argument deprecated
# > foo(paging = T)
# Warning message:
#   In foo(paging = T) : argument deprecated

As @Roland points out, it should also be mentioned in the documentation for that function that the argument is now deprecated.