Not documenting a function and not getting a check error?

Duncan Murdoch writes:
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".
Actually, IIuc the infrastructure is there, but it is not used.
print.codoc() has

    ## In general, functions in the code which only have an \alias but
    ## no \usage entry are not necessarily a problem---they might be
    ## mentioned in other parts of the Rd object documenting them, or be
    ## 'internal'.  However, if a package has a namespace, then all
    ## *exported* functions should have \usage entries (apart from
    ## defunct functions and S4 generics, see the above comments for
    ## functions_missing_from_usages).  Currently, this information is
    ## returned in the codoc object but not shown.  Eventually, we might
    ## add something like
    ##     functions_missing_from_usages <-
    ##         attr(x, "functions_missing_from_usages")
    ##     if(length(functions_missing_from_usages)) {
    ##         writeLines("Exported functions without usage information:")
    ##         .pretty_print(functions_in_code_not_in_usages)
    ##         writeLines("")
    ##     }
    ## similar to the above.

which goes back to sometimes 2009 ...

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

______________________________________________
R-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Not documenting a function and not getting a check error?

Thread (6 messages)