R devel - Apr 2023 - Should '@" now be listed in tools:::.get_internal_S3_generics() ?

>>>>> Karolis Koncevi?ius writes:
Can you pls try again with r84341 or later?

Best
-k
> A more concrete example in order to correct my vague messages below.
> Writing an R package that uses `@` and `@<-` as S3 generics. Line from
manual pages in .Rd files:
>     \method{@}{newclass}(object, name) <- value
> Throws this error during R CMD check ?as-cran
>     Bad \usage lines found in documentation object ?code?:
>       <unescaped bksl>method{@}{newclass}(object, name) <- value
> This error is due to tools::checkDocFiles eventually calling
tools:::.S3_method_markup_regexp and not finding `@` as a valid for S3.
> This error is gone if we adjust tools:::.S3_method_markup_regexp to pass
for ?@? by adding ?\\@? to regexp.
> Please note that this now is not dependant on using or not using roxygen2
> KK.
>> On Apr 29, 2023, at 12:53 AM, Karolis Koncevi?ius
<karolis.koncevicius at gmail.com> wrote:
>> 
>> Thank you for such a quick reply, Gabriel,
>> 
>> I am not too familiar with the package tools, so cannot speak too
confidently, but below is how I see the issue currently.
>> 
>> The issue is not for external packages to rely on unexported functions
from tools::, rather the issue is that 'R CMD check ?as-cran' runs those
functions from tools:: in order to check the validity of Rd files (from any
package). R 4.3.0 added @ as internal S3 generic. However, package tools does
not recognise it as valid in Rd files and throws errors when it sees S3 method
declared for @ in the Rd usage lines.
>> 
>> So any package that will try to use @ generic will run into the issue,
without attempting to use internal S3 functions in their code, but during the R
CMD check step.
>> 
>> Hope I am being clearer now, and not missing something important (all
these things: both @ as generic and tools:: package are quite new to me),
>> Karolis K.
>> 
>>> On Apr 29, 2023, at 12:38 AM, Gabriel Becker <gabembecker at
gmail.com> wrote:
>>> 
>>> Karolis,
>>> 
>>> It seems likely, without having looked myself, that you could be
correct about the issue, but it does seem worth noting that both of the
functions you have mentioned are not exported, and thus not part of the API that
extension packages are allowed to use and rely on.
>>> 
>>> If retrieving the list of "internal S3 generics" is
something package and user code is allowed to do, the real fix seems to go
beyond what you're suggesting, to actually providing an API entry point that
gives the relevant information (maybe in an identical form to how those internal
functions do so, maybe not). If it's not, for some principled reason,
something R-core wants to support package and user code doing, then the fact
that the new thing doesn't work automatically with roxygen2 would become the
roxygen maintainers' job to fix or document.
>>> 
>>> I do not know whether R-core feels this is something packages/users
should be able to do; both decisions strike me as possible, to be honest,
depending on details I don't know and/or am not privy to.
>>> 
>>> Best,
>>> ~G 
>>> 
>>> On Fri, Apr 28, 2023 at 1:49?PM Karolis Koncevi?ius
<karolis.koncevicius at gmail.com <mailto:karolis.koncevicius at
gmail.com>> wrote:
>>>> This issue might go deeper - I was not successful in passing R
CMD checks for the usage files. R CMD check kept showing errors for `@`
declarations, even thou they were identical to `$` declarations (which passed
fine).
>>>> 
>>>> Seems like the usage check functions are not prepared for `@` -
also in tools:::.S3_method_markup_regexp
>>>> 
>>>> > On Apr 28, 2023, at 10:34 PM, Karolis Koncevi?ius
<karolis.koncevicius at gmail.com <mailto:karolis.koncevicius at
gmail.com>> wrote:
>>>> > 
>>>> > I was building a package that uses the new generic @ and
kept having errors with ?roxygen2? documentation. ?roxygen2? generated NAMESPACE
added `@.newclass` as a newly exported function, not as a S3method.
>>>> > 
>>>> > At first I thought this must be a bug in roxygen2 and they
lag behind the new developments in R. But after some investigation I found that
?roxygen2? is using tools:::.get_internal_S3_generis() to decide if the method
should be exported as S3method or not. For some reason ?@<-? is listed in
there, but ?@? is not.
>>>> > 
>>>> > Am I missing some context, or is this an oversight?
>>>> > 
>>>> > Kind regards,
>>>> > Karolis Koncevicius
>>>> 
>>>> ______________________________________________
>>>> R-devel at r-project.org <mailto:R-devel at
r-project.org> mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>> 
> 	[[alternative HTML version deleted]]
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

Hello Kurt,

With r84341 it now works on my side.

Warm regards,
Karolis K.
> On Apr 29, 2023, at 1:24 PM, Kurt Hornik <Kurt.Hornik at wu.ac.at>
wrote:
> 
>>>>>> Karolis Koncevi?ius writes:
> 
> Can you pls try again with r84341 or later?
> 
> Best
> -k
> 
>> A more concrete example in order to correct my vague messages below.
>> Writing an R package that uses `@` and `@<-` as S3 generics. Line
from manual pages in .Rd files:
> 
>>    \method{@}{newclass}(object, name) <- value
> 
>> Throws this error during R CMD check ?as-cran
> 
>>    Bad \usage lines found in documentation object ?code?:
>>      <unescaped bksl>method{@}{newclass}(object, name) <-
value
> 
>> This error is due to tools::checkDocFiles eventually calling
tools:::.S3_method_markup_regexp and not finding `@` as a valid for S3.
>> This error is gone if we adjust tools:::.S3_method_markup_regexp to
pass for ?@? by adding ?\\@? to regexp.
> 
>> Please note that this now is not dependant on using or not using
roxygen2
>> KK.
> 
>>> On Apr 29, 2023, at 12:53 AM, Karolis Koncevi?ius
<karolis.koncevicius at gmail.com> wrote:
>>> 
>>> Thank you for such a quick reply, Gabriel,
>>> 
>>> I am not too familiar with the package tools, so cannot speak too
confidently, but below is how I see the issue currently.
>>> 
>>> The issue is not for external packages to rely on unexported
functions from tools::, rather the issue is that 'R CMD check ?as-cran'
runs those functions from tools:: in order to check the validity of Rd files
(from any package). R 4.3.0 added @ as internal S3 generic. However, package
tools does not recognise it as valid in Rd files and throws errors when it sees
S3 method declared for @ in the Rd usage lines.
>>> 
>>> So any package that will try to use @ generic will run into the
issue, without attempting to use internal S3 functions in their code, but during
the R CMD check step.
>>> 
>>> Hope I am being clearer now, and not missing something important
(all these things: both @ as generic and tools:: package are quite new to me),
>>> Karolis K.
>>> 
>>>> On Apr 29, 2023, at 12:38 AM, Gabriel Becker <gabembecker at
gmail.com> wrote:
>>>> 
>>>> Karolis,
>>>> 
>>>> It seems likely, without having looked myself, that you could
be correct about the issue, but it does seem worth noting that both of the
functions you have mentioned are not exported, and thus not part of the API that
extension packages are allowed to use and rely on.
>>>> 
>>>> If retrieving the list of "internal S3 generics" is
something package and user code is allowed to do, the real fix seems to go
beyond what you're suggesting, to actually providing an API entry point that
gives the relevant information (maybe in an identical form to how those internal
functions do so, maybe not). If it's not, for some principled reason,
something R-core wants to support package and user code doing, then the fact
that the new thing doesn't work automatically with roxygen2 would become the
roxygen maintainers' job to fix or document.
>>>> 
>>>> I do not know whether R-core feels this is something
packages/users should be able to do; both decisions strike me as possible, to be
honest, depending on details I don't know and/or am not privy to.
>>>> 
>>>> Best,
>>>> ~G 
>>>> 
>>>> On Fri, Apr 28, 2023 at 1:49?PM Karolis Koncevi?ius
<karolis.koncevicius at gmail.com <mailto:karolis.koncevicius at
gmail.com> <mailto:karolis.koncevicius at gmail.com>> wrote:
>>>>> This issue might go deeper - I was not successful in
passing R CMD checks for the usage files. R CMD check kept showing errors for
`@` declarations, even thou they were identical to `$` declarations (which
passed fine).
>>>>> 
>>>>> Seems like the usage check functions are not prepared for
`@` - also in tools:::.S3_method_markup_regexp
>>>>> 
>>>>>> On Apr 28, 2023, at 10:34 PM, Karolis Koncevi?ius
<karolis.koncevicius at gmail.com <mailto:karolis.koncevicius at
gmail.com> <mailto:karolis.koncevicius at gmail.com>> wrote:
>>>>>> 
>>>>>> I was building a package that uses the new generic @
and kept having errors with ?roxygen2? documentation. ?roxygen2? generated
NAMESPACE added `@.newclass` as a newly exported function, not as a S3method.
>>>>>> 
>>>>>> At first I thought this must be a bug in roxygen2 and
they lag behind the new developments in R. But after some investigation I found
that ?roxygen2? is using tools:::.get_internal_S3_generis() to decide if the
method should be exported as S3method or not. For some reason ?@<-? is listed
in there, but ?@? is not.
>>>>>> 
>>>>>> Am I missing some context, or is this an oversight?
>>>>>> 
>>>>>> Kind regards,
>>>>>> Karolis Koncevicius
>>>>> 
>>>>> ______________________________________________
>>>>> R-devel at r-project.org <mailto:R-devel at
r-project.org> <mailto:R-devel at r-project.org> mailing list
>>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>> 
> 
> 
>> 	[[alternative HTML version deleted]]
> 
>> ______________________________________________
>> R-devel at r-project.org <mailto:R-devel at r-project.org>
mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel

	[[alternative HTML version deleted]]