[Rd] proposed modifications to deprecated

[Kurt Hornik]

>>>>> Robert Gentleman writes:

> Hi,
>    Over the past six months we have had a few problems with deprecation 
> and Seth Falcon and I want to propose a few additions to the mechanism 
> that will help deal with cases other than the deprecation of functions.

>   In the last release one of the arguments to La.svd was deprecated, but 
> the warning message was very unclear and suggested that in fact La.svd 
> was deprecated.
>    Adding a third argument to .Deprecated, msg say (to be consistent 
> with the internal naming mechanism) that contains the message string 
> would allow for handling the La.svd issue in a more informative way. It 
> is a strict addition so no existing code is likely to be broken.

That's a very nice idea afaic.

>    We also need to deprecate data from time to time. Since the field of 
> genomics is moving fast as good example from five years ago is often no 
> longer a good example today. This one is a bit harder, but we can modify
>    tools:::.make_file_exts("data")

>    to first look for a ".DEP" extension (this does not seem to be a 
> widely used extension), and if such a file exists, ie NameofData.DEP
>   one of two things happens: if it contains a character string we use 
> that for the message (we could source it for the message?), if not print 
> a standard message (just as .Deprecated does) and then continue with the 
> search using the other file extensions.

>    Defunct could be handled similarly.

>   Comments, alternative suggestions?

I thought about more declarative (R-code-based) alternatives, but using
a new extension seems most convenient (as it also achieves registration
with no need for further code analysis).

I would have a slight preference for using ".deprecated", and similar
using ".defunct" if necessary.

One of the annoying things about the current two-cycle deprecate/defunct
process is that R CMD check can only catch usages in code run by the
examples.  It would be nice to use the codetools infrastructure for an
improved code analysis here (checking for calling deprecated "global"
variables or function arguments (e.g., for the La.svd() example).  Of
course, this would not only require that codetools can be made to work
again for 2.4.0 (and we do pay a heavy price for the NULL environment
changes here afaic), but also that we have a registry for deprecated
things ...

Btw, is there a formal way of deprecating arguments to functions?  Part
of the possible La.svd() confusion might come from using

    if(is.numeric(x) && method == "dgesvd")
        .Deprecated('La.svd(method = "dgesvd")')

Best
-k