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

[Duncan Murdoch]

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 using gmail.com 
> <mailto:murdoch.duncan using 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 using gmail.com <mailto:murdoch.duncan using 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 using r-project.org <mailto:R-devel using r-project.org> mailing list
>     https://stat.ethz.ch/mailman/listinfo/r-devel
>     <https://stat.ethz.ch/mailman/listinfo/r-devel>
>