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

[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



-- 
http://hadley.nz