[R-pkg-devel] find functions with missing Rd tags

[Martin Morgan]

I looked at the help page for ?tools::Rd_db and came up with this script; maybe not perfect...

Create a database of Rd information for the package of interest

    library(tools)
    pkg_of_interest <- "stats"
    db <- Rd_db(pkg_of_interest)

Extract relevant fields / summary of fields into a database. This is from the example code on the ?Rd_db page. There can only be one `name` or `value` tag, but several `alias` tags
    
    name <- lapply(db, tools:::.Rd_get_metadata, "name")
    alias <- lapply(db, tools:::.Rd_get_metadata, "alias")
    value <- lapply(db, tools:::.Rd_get_metadata, "value")
    
    n_aliases <- lengths(alias)
    df <- data.frame(
        file_name = rep(names(db), n_aliases),
        name = rep(unlist(name, use.names = FALSE), n_aliases),
        alias = unlist(alias, use.names = FALSE),
        has_value = rep(lengths(value) > 0, n_aliases)
    )

Create subsets of the database, and find the aliases that have no values. This is trying to allow for the possibility that an alias occurs in more than one help file (is this allowed?)

    alias_with_value <- subset(df, has_value)
    alias_without_value <- subset(df, !has_value)    
    no_value <- subset(alias_without_value, !alias %in% alias_with_value$alias)

Find all the exports in the package, and subset the help pages to just those.

    exports <- getNamespaceExports(pkg_of_interest)
    subset(no_value, alias %in% exports)

This still requires some manual review; here are some entries with comments

                    file_name               name               alias has_value
    84              biplot.Rd             biplot              biplot     FALSE

yep, ?biplot finds a help page that documents biplot() and does not have a value section. It does have a 'Side effect' section, but I think that's non-standard

    268      glm.summaries.Rd      glm.summaries       residuals.glm     FALSE

This is a method for the generic residuals() applied to an object of class glm; it should still have a value section, I think...

    627      stats-defunct.Rd      stats-defunct         arima0.diag     FALSE

I guess it  makes sense for defunct functions not to be fully documented, though maybe it would be helpful for those trying to migrate their code...

Martin Morgan
    

On 6/23/21, 1:58 PM, "R-package-devel on behalf of Alex Chubaty" <r-package-devel-bounces using r-project.org on behalf of alex.chubaty using gmail.com> wrote:

    During a recent package submission process, a CRAN maintainer showed one of
    their checks found missing \value{} documentation in some package Rd files,
    and asked us to ensure all exported functions have their return values
    described.

    This check (for missing Rd values) is not run by the default checks, so I
    have no idea how to quickly identify which functions are missing those
    components, without manually inspecting everything. I am hoping that
    someone here can tell me which special R CMD check incantation, or similar
    I can use to find _exported_ functions with missing Rd tags.

    Thank you,
    Alex

    	[[alternative HTML version deleted]]

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