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