[Bioc-devel] deprecation guidelines

[Pages, Herve]

Hi Sam,

On 4/11/19 10:47, Samuela Pollack wrote:
> Dear Bioconductor,
>
> We are deprecating part of a package. I am following the guidelines in 
> the "Function Deprecation Guidelines" page at bioconductor.org and I 
> have a few questions:
>
> (i) Deprecating a S4 method which has the same name in another S4 
> class. We have two DelayedArray backends. Functions like dim and 
> dimnames are deprecated in one but not in the other. Should those 
> functions be listed in the ThePkg-deprecated document? With the name 
> of the backend that's being deprecated? With a note about the backend 
> that is *not* being deprecated?

Before their deprecation these methods should normally already be 
documented somewhere. In particular there should already be aliases and 
\usage entries somewhere for them. For example if foo() is the generic, 
the alias for the foo,SomeClass method is:

   \alias{foo,SomeClass-method}

and the \usage entry for this method looks like this:

   \S4method{foo}{SomeClass}(x, ...)

When deprecating this method, the \alias and \usage entry should be 
moved to the MyPkg-deprecated man page. Note that the "Function 
Deprecation Guidelines" only suggests to list the deprecated methods 
(and their replacements) in the \details section, but it's fine to also 
list them in a \usage section.

>
> (ii) Deprecating a S4 class. Should this look just like a function in 
> ThePkg-deprecated?

Same as for a method except that, strictly speaking, there is no notion 
of \usage entry for an S4 class, only for its constructor function (if 
there is one). So the aliases for the class and its constructor, and the 
\usage entry for the constructor, should be moved to the 
MyPkg-deprecated man page.

>
>
> (iii) subscript, double-subscript, assign-to-property (property<-) 
> operators. Should they be included in ThePkg-deprecated.Rd? In favor: 
> they are being deprecated for the class they pertain to. Against: we 
> certainly aren't deprecating the subscript operator in general.

These are methods e.g. the [,SomeClass, [[,SomeClass, and [<-,SomeClass 
methods. The procedure to deprecate them is the same as for deprecating 
methods in general. So them as (i).

Hope this helps,

H.

>
> thanks,
>
> - Sam
>
> _______________________________________________
> Bioc-devel using r-project.org mailing list
> https://urldefense.proofpoint.com/v2/url?u=https-3A__stat.ethz.ch_mailman_listinfo_bioc-2Ddevel&d=DwICAg&c=eRAMFD45gAfqt84VtBcfhQ&r=BK7q3XeAvimeWdGbWY_wJYbW0WYiZvSXAJJKaaPhzWA&m=c7mY7SviNf8WObwMM13uYGQuvB87RX3qS6eV5nIZsYg&s=QzjewaW8MNTVLiVirE1ytWId_dqFeUjSfYL5i6US2zM&e= 
>

-- 
Hervé Pagès

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages using fredhutch.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319