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

[Kurt Hornik]

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

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