Check Code/Documentation Consistency
Find inconsistencies between actual and documented structure
of R objects in a package.
codoc compares names and
optionally also corresponding positions and default values of the
arguments of functions.
compare slot names of S4 classes and variable names of data sets,
codoc(package, dir, lib.loc = NULL, use.values = NULL, verbose = getOption("verbose")) codocClasses(package, lib.loc = NULL) codocData(package, lib.loc = NULL)
- a character string naming an installed package.
- a character string specifying the path to a package's root
source directory. This must contain the subdirectories man
with R documentation sources (in Rd format) and R with R
code. Only used if
packageis not given.
- a character vector of directory names of R libraries,
NULL. The default value of
NULLcorresponds to all libraries currently known. The specified library trees are used to search for
FALSE, do not use function default values when comparing code and docs. Otherwise, compare all default values if
TRUE, and only the ones documented in the usage otherwise (default).
- a logical. If
TRUE, additional diagnostics are printed.
The purpose of
codoc is to check whether the documented usage
of function objects agrees with their formal arguments as defined in
the R code. This is not always straightforward, in particular as the
usage information for methods to generic functions often employs the
name of the generic rather than the method.
The following algorithm is used. If an installed package is used, it
is loaded (unless it is the base package), after possibly
detaching an already loaded version of the package. Otherwise, if the
sources are used, the R code files of the package are collected and
sourced in a new environment. Then, the usage sections of the Rd
files are extracted and parsed as much as possible to give
the formals documented. For interpreted functions in the code
environment, the formals are compared between code and documentation
according to the values of the argument
sections are used if present; their occurrence is reported if
verbose is true.
If a package has a namespace both exported and unexported objects are checked, as well as registered S3 methods. (In the unlikely event of differences the order is exported objects in the package, registered S3 methods and finally objects in the namespace and only the first found is checked.)
Currently, the R documentation format has no high-level markup for the
basic structure of classes and data sets (similar to the usage
sections for function synopses). Variable names for data frames in
documentation objects obtained by suitably editing templates
prompt are recognized by
and used provided that the documentation object is for a single data
frame (i.e., only has one alias).
handles slot names for classes in documentation objects obtained by
editing shells created by
Help files named pkgname-defunct.Rd for the appropriate pkgname are checked more loosely, as they may have undocumented arguments.
codocreturns an object of class
"codoc". Currently, this is a list which, for each Rd object in the package where an inconsistency was found, contains an element with a list of the mismatches (which in turn are lists with elements
docs, giving the corresponding arguments obtained from the function's code and documented usage).
codocDatareturn objects of class
"codocData", respectively, with a structure similar to class
The default for
use.values has been changed from
NULL, for R versions 1.9.0 and later.