Skip to content

Not documenting a function and not getting a check error?

6 messages · Duncan Murdoch, Deepayan Sarkar, Kevin Coombes +1 more

Original
Duncan Murdoch
# 
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?

Duncan Murdoch
Deepayan Sarkar
#
On Fri, Jan 6, 2023 at 1:49 AM Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
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.

Best,
-Deepayan
Duncan Murdoch
#
On 05/01/2023 10:10 p.m., Deepayan Sarkar wrote:
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
Kevin Coombes
# 
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. 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>
wrote:

  
  


  


      

    

    

      
      

        


  

        

      Duncan Murdoch
    

    

      
      #
    

  


  

      
On 06/01/2023 5:25 a.m., Kevin Coombes wrote:

            

      
      
      
    

        
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

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    
2 days later

    

      
      

        


  

        

      Kurt Hornik
    

    

      
      #
    

  


  

          

      
      
      
    

        
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