[R-pkg-devel] Unfortunate function name generic.something
Duncan Murdoch
murdoch@dunc@n @end|ng |rom gm@||@com
Mon May 8 18:29:23 CEST 2023
On 08/05/2023 12:10 p.m., Ulrike Groemping wrote:
> Am 08.05.2023 um 15:48 schrieb 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
> It solved the documentation warning issue, but another issue followed
> suit (found in the submission pretests only):
>
> "Mismatches for apparent methods not registered:
> levels:
> function(x)
> levels.no:
> function(xx)"
>
> I now changed the argument of levels.no to x, registered the method (as
> I was under the impression that not registering it would trigger the
> next complaint; of course, registering it might make it more likely to
> be mis-used). For preventing unnoticed problems, I made the function
> throw a meaningful error message ("DoE.base:::levels.no is not a method
> for the generic base::levels") in the (hopefully unlikely) case that it
> is handed an object of class "no" by someone who wants to use a levels
> method on that object. This version now passed the pretest checks.
I think that registering it as an S3 method makes the potential problem
worse, because it makes it much more visible. That's assuming you now
have something like
S3method(levels, no)
in your NAMESPACE file, so every use of levels() by the user or in any
package could potentially call levels.no if your package is loaded.
Duncan Murdoch
>
> Ulrike Groemping
>
>>
>>>
>>> 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
>>>>
>>
More information about the R-package-devel
mailing list