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

[Duncan Murdoch]

On 08/05/2023 8:28 a.m., Ulrike Groemping wrote:
> Thanks, Duncan. I appreciate the view that levels.no acts as an S3
> method for the generic levels, if an object of class "no" is handed to
> it. However, as the function is not intended as an S3 method, it does
> not make sense to document it as such. As the function is internal only,
> which makes the scenario that it causes trouble extremely unlikely, I
> will simply comment out the usage line for the function in order to get
> rid of the note but keep the usage visible. I hope that this is OK.

I think that should solve the warning issue, and it's better than 
documenting it as an S3 method when it's not intended to be one.

I don't know how likely it is to cause trouble.  You do call levels(), 
but I don't know if you ever call it on objects that weren't created 
internally.  If so, then there's the possibility that one of them will 
have that "no" class for a completely unrelated reason, and then there 
will be trouble.

Duncan Murdoch

> 
> Best, Ulrike
> 
> Am 08.05.2023 um 13:58 schrieb 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
>>