[R-pkg-devel] Unfortunate function name generic.something

[Duncan Murdoch]

There really isn't such a thing as "a function that looks like an S3 
method, but isn't".  If it looks like an S3 method, then in the proper 
circumstances, it will be called as one.

In your case the function name is levels.no, and it isn't exported.  So 
if you happen to have an object with a class inheriting from "no", and 
you call levels() on it, levels.no might be called.

This will only affect users of your package indirectly.  If they have 
objects inheriting from "no" and call levels() on them, levels.no will 
not be called.  But if they pass such an object to one of your package 
functions, and that function calls levels() on it, they could end up 
calling levels.no().  It all depends on what other classes that object 
inherits from.

You can test this yourself.  Set debugging on any one of your functions, 
then call it in the normal way.  Then while still in the debugger set 
debugging on levels.no, and create an object using

   x <- structure(1, class = "no")

and call levels(x).  You should break to the code of levels.no.

That is why the WRE manual says "First, a caveat: a function named 
gen.cl will be invoked by the generic gen for class cl, so do not name 
functions in this style unless they are intended to be methods."

So probably the best solution (even if inconvenient) is to rename 
levels.no to something that doesn't look like an S3 method.

Duncan Murdoch

On 08/05/2023 5:50 a.m., Ulrike Groemping wrote:
> Thank your for the solution attempt. However, using the keyword internal
> does not solve the problem, the note is still there. Any other proposals
> for properly documenting a function that looks like an S3 method, but isn't?
> 
> Best, Ulrike
> 
> Am 05.05.2023 um 12:56 schrieb Iris Simmons:
>> You can add
>>
>> \keyword{internal}
>>
>> to the Rd file. Your documentation won't show up the in the pdf
>> manual, it won't show up in the package index, but you'll still be
>> able to access the doc page with ?levels.no <http://levels.no> or
>> help("levels.no <http://levels.no>").
>>
>> This is usually used in a package's deprecated and defunct doc pages,
>> but you can use it anywhere.
>>
>> On Fri, May 5, 2023, 06:49 Ulrike Groemping
>> <ulrike.groemping using bht-berlin.de> wrote:
>>
>>      Dear package developeRs,
>>
>>      I am working on fixing some notes regarding package DoE.base.
>>      One note refers to the function levels.no <http://levels.no> and
>>      complains that the
>>      function is not documented as a method for the generic function
>>      levels.
>>      Actually, it is not a method for the generic levels, but a standalone
>>      internal function that I like to have documented.
>>
>>      Is there a way to document the function without renaming it and
>>      without
>>      triggering a note about method documentation?
>>
>>      Best, Ulrike
>>
>>      --
>>      ##############################################
>>      ## Prof. Ulrike Groemping
>>      ## FB II
>>      ## Berliner Hochschule für Technik (BHT)
>>      ##############################################
>>      ## prof.bht-berlin.de/groemping <http://prof.bht-berlin.de/groemping>
>>      ## Phone: +49(0)30 4504 5127
>>      ## Fax:   +49(0)30 4504 66 5127
>>      ## Home office: +49(0)30 394 04 863
>>      ##############################################
>>
>>      ______________________________________________
>>      R-package-devel using r-project.org mailing list
>>      https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>
> 
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel