[R-pkg-devel] Unfortunate function name generic.something
Ulrike Groemping
u|r|ke@groemp|ng @end|ng |rom bht-ber||n@de
Mon May 8 18:10:22 CEST 2023
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.
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