Kevin Coombes
2023-Jan-06 10:25 UTC
[Rd] Not documenting a function and not getting a check error?
I am fairly certain that the check for documentation is really just a check for the presence of the function name in an "alias" line. My circumstantial evidence, from a package in the early stages of development, came from changing the name of a function. I updated everything else (usage, examples, etc.) but forgot to change the alias. Got a warning that the newly named function was not documented. It took me a while to figure out why R CMD check was still complaining. I am also pretty sure that, when looking for help in at least one existing package (can't remember which one), I clicked on the link and got sent to a page that said absolutely nothing about the function I was interested in. On Fri, Jan 6, 2023, 4:48 AM Duncan Murdoch <murdoch.duncan at gmail.com> wrote:> On 05/01/2023 10:10 p.m., Deepayan Sarkar wrote: > > On Fri, Jan 6, 2023 at 1:49 AM Duncan Murdoch <murdoch.duncan at gmail.com> > wrote: > >> > >> I'm in the process of a fairly large overhaul of the exports from the > >> rgl package, with an aim of simplifying maintenance of the package. > >> During this work, I came across the reverse dependency geomorph that > >> calls the rgl.primitive function. > >> > >> I had forgotten that rgl.primitive was still exported: I've been > >> thinking of it as an internal function for a few years now. I was > >> surprised geomorph was able to call it. > >> > >> Particularly surprising to me was the fact that it is not properly > >> documented. One of the help topics lists it as an alias, but it > >> contains no usage info, and is not mentioned in the .Rd file other than > >> the alias. And yet "R CMD check rgl" has never complained about it. > >> > >> Is this intentional? > > > > Does the Rd file that documents it have \keyword{internal}? These are > > not checked fully (as I realized recently while working on the help > > system), and I guess that's intentional. > > No, not marked internal. Here's a simple example: a package that > exports f and g, and has only one help page: > > --------------------- > NAMESPACE: > --------------------- > export(f, g) > --------------------- > > --------------------- > R/source.R: > --------------------- > f <- function() "this is f" > > g <- function() "this is g" > --------------------- > > --------------------- > man/f.Rd: > --------------------- > \name{f} > \alias{f} > \alias{g} > \title{ > This is f. > } > \description{ > This does nothing > } > \usage{ > f() > } > --------------------- > > > No complaints about the lack of documentation of g. > > Duncan Murdoch > > ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel >[[alternative HTML version deleted]]
Duncan Murdoch
2023-Jan-06 10:57 UTC
[Rd] Not documenting a function and not getting a check error?
On 06/01/2023 5:25 a.m., Kevin Coombes wrote:> I am fairly certain that the check for documentation is really just a > check for the presence of the function name in an "alias" line.Yes, that's what the test does, and that's fine. The problem is with the usage test in tools::codoc(). If I had incorrect arguments specified for a documented function, I'd be warned. If I skip the usage docs completely, I am not warned. I think the test belongs around here in the source: https://github.com/r-devel/r-svn/blob/b57918fd104962415a752ea7db12dcf4f3f5219f/src/library/tools/R/QC.R#L585 If you look there, you see a variable named "functions_in_usages_not_in_code" but nothing named "functions_in_code_not_in_usages". Duncan Murdoch My> circumstantial evidence, from a package in the early stages of > development, came from changing the name of a function. I updated > everything else (usage, examples, etc.) but forgot to change the alias. > Got a warning that the newly named function was not documented. It took > me a while to figure out why R CMD check was still complaining. > > I am also pretty sure that, when looking for help in at least one > existing package (can't remember which one), I clicked on the link and > got sent to a page that said absolutely nothing about the function I was > interested?in. > > On Fri, Jan 6, 2023, 4:48 AM Duncan Murdoch <murdoch.duncan at gmail.com > <mailto:murdoch.duncan at gmail.com>> wrote: > > On 05/01/2023 10:10 p.m., Deepayan Sarkar wrote: > > On Fri, Jan 6, 2023 at 1:49 AM Duncan Murdoch > <murdoch.duncan at gmail.com <mailto:murdoch.duncan at gmail.com>> wrote: > >> > >> I'm in the process of a fairly large overhaul of the exports > from the > >> rgl package, with an aim of simplifying maintenance of the package. > >> During this work, I came across the reverse dependency geomorph that > >> calls the rgl.primitive function. > >> > >> I had forgotten that rgl.primitive was still exported:? I've been > >> thinking of it as an internal function for a few years now.? I was > >> surprised geomorph was able to call it. > >> > >> Particularly surprising to me was the fact that it is not properly > >> documented.? One of the help topics lists it as an alias, but it > >> contains no usage info, and is not mentioned in the .Rd file > other than > >> the alias.? And yet "R CMD check rgl" has never complained about it. > >> > >> Is this intentional? > > > > Does the Rd file that documents it have \keyword{internal}? These are > > not checked fully (as I realized recently while working on the help > > system), and I guess that's intentional. > > No, not marked internal.? Here's a simple example:? a package that > exports f and g, and has only one help page: > > --------------------- > NAMESPACE: > --------------------- > export(f, g) > --------------------- > > --------------------- > R/source.R: > --------------------- > f <- function() "this is f" > > g <- function() "this is g" > --------------------- > > --------------------- > man/f.Rd: > --------------------- > \name{f} > \alias{f} > \alias{g} > \title{ > This is f. > } > \description{ > This does nothing > } > \usage{ > f() > } > --------------------- > > > No complaints about the lack of documentation of g. > > Duncan Murdoch > > ______________________________________________ > R-devel at r-project.org <mailto:R-devel at r-project.org> mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel > <https://stat.ethz.ch/mailman/listinfo/r-devel> >