search

r-lib / roxygen2

Generate R package documentation from inline R comments
https://roxygen2.r-lib.org
Other
591 stars 232 forks source link

does roxygen2 support internal S3 methods? #1654

Closed tdhock closed 15 hours ago

tdhock commented 1 week ago

Hi! roxygen2 gives warnings like "S3 method getStrips.grid needs @export or @exportS3method" for animint2, https://github.com/animint/animint2/issues/148 I see these warnings come from https://github.com/r-lib/roxygen2/blob/9652d15221109917d46768e836eaf55e33c21633/R/namespace.R#L409

These S3 methods are internal (we don't want to export them). Is there any other way to supprress this warning?

tdhock commented 1 week ago

John Fox also was wondering about this on R-devel, https://stat.ethz.ch/pipermail/r-package-devel/2024q3/011069.html

olivroy commented 1 week ago

See https://github.com/r-lib/roxygen2/issues/1592#issuecomment-1986069247

tdhock commented 1 week ago

that comment says from R-3.5 onward, S3 methods should be registered even if they are not exported. How do you do that with roxygen2? the warning says needs @export or @exportS3Method but I do not want to export.

olivroy commented 1 week ago

Well, that's the thing, the @export tag without documentation has the effect of registering them. https://roxygen2.r-lib.org/dev/articles/namespace.html?q=s3#s3

tdhock commented 15 hours ago

right, thanks, that documentation is adequate, I just did not find it until you linked it. Thanks

'While S3 methods are regular functions with a special naming scheme, their “export” works a bit differently. S3 methods are exported only in the sense that calling the generic with the appropriate class will call the method; a user can’t directly access the method definition by typing its name. A more technically correctly term would be to say that the method is registered so that the generics can find it.'