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

[Ulrike Groemping]

I certainly could, but I'm using this little convenience function it in 
so many places (and packages) that this would be a massive amount of 
work - doesn't feel justified, given the tiny chance of causing a problem.
Ulrike

Am 08.05.2023 um 14:45 schrieb Hadley Wickham:
> If it's internal only, you could change the name to levels_no()?
> Hadley
>
> On Mon, May 8, 2023 at 7:28 AM Ulrike Groemping
> <ulrike.groemping using bht-berlin.de> 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.
>>
>> 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
>> ______________________________________________
>> R-package-devel using r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
>