[R-pkg-devel] Deprecating apparent S3 method, changing name

[Murray Efford]

Thanks for your excellent exposition of the problem, Ivan. The set-aside option would be attractive in the long term and make it easier to fix historical errors like mine. Presumably there is also a downside to creating a safe space for badly named functions.

I am tossing up between (i) appealing to CRAN to allow the submission through with NOTEs until it feels safe to remove the functions with misleading names altogether, and (ii) removing them now and warning users about the new names in an  onLoad message.
Murray
________________________________
From: Ivan Krylov <ikrylov using disroot.org>
Sent: Friday, 27 September 2024 08:48
To: Murray Efford via R-package-devel <r-package-devel using r-project.org>
Cc: Murray Efford <murray.efford using otago.ac.nz>
Subject: Re: [R-pkg-devel] Deprecating apparent S3 method, changing name

� Wed, 25 Sep 2024 05:13:31 +0000
Murray Efford via R-package-devel <r-package-devel using r-project.org> �����:

> When I deprecate the old functions (by exporting a shell function
> that calls .Deprecated and the new function), I get a package check
> note for e.g. esa.plot "* checking S3 generic/method consistency ...
> NOTE Apparent methods for exported generics not registered: etc."
>
> This is understandable, but how can I avoid it while properly
> deprecating the old functions?

R CMD check has a hard-coded list of functions that should not be
considered S3 methods, in tools:::nonS3methods(). All other functions
that start with the name of an exported generic followed by a dot will
be considered unregistered S3 methods.

Theoretically speaking, if there was a place in your package where you
called the esa() generic with a user-supplied object, esa.plot() would
be a reachable S3 method, because the user would be able to construct
structure(list(), class = 'plot') and give it to your package code to
call esa(plot_object) and have it dispatched to esa.plot(). (Which
wouldn't be useful to the user, but that's how S3 works.)

I'm afraid that the NOTE is unavoidable in a package that has both an
esa() generic and an esa.plot() non-method function. Perhaps it could
be explained in the submission comment? (Especially since esa.plot()
currently seems unreachable as an S3 method to normal users of the
package.)

I wonder if it's possible to set aside a "please don't consider me for
S3 dispatch" bit in the CLOSXP objects. Then package authors would be
able to set it on their unfortunately named functions, R CMD check
would look it up before considering them to be unexported methods, and
the function findFunWithBaseEnvAfterGlobalEnv() that's responsible for
looking up non-registered S3 methods during UseMethod() would skip over
such closures.

--
Best regards,
Ivan

	[[alternative HTML version deleted]]