[Rd] Not documenting a function and not getting a check error?

Duncan Murdoch
Fri, 06 Jan 2023 10:57:58 -0000

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>
>