codoc                 package:tools                 R Documentation

_C_h_e_c_k _C_o_d_e/_D_o_c_u_m_e_n_t_a_t_i_o_n _C_o_n_s_i_s_t_e_n_c_y

_D_e_s_c_r_i_p_t_i_o_n:

     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.  'codocClasses' and 'codocData' compare slot names
     of S4 classes and variable names of data sets, respectively.

_U_s_a_g_e:

     codoc(package, dir, lib.loc = NULL,
           use.values = NULL, verbose = getOption("verbose"))
     codocClasses(package, lib.loc = NULL)
     codocData(package, lib.loc = NULL)

_A_r_g_u_m_e_n_t_s:

 package: a character string naming an installed package.

     dir: 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 'package' is not given.

 lib.loc: a character vector of directory names of R libraries, or
          'NULL'.  The default value of 'NULL' corresponds to all
          libraries currently known.  The specified library trees are
          used to search for 'package'.

use.values: if '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).

 verbose: a logical.  If 'TRUE', additional diagnostics are printed.

_D_e_t_a_i_l_s:

     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 'use.values'.  Synopsis sections are used if present;
     their occurrence is reported if 'verbose' is true.

     If a package has a name space 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 name space 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' created by 'prompt' are recognized by 'codocData' and
     used provided that the documentation object is for a single data
     frame (i.e., only has one alias).  'codocClasses' analogously
     handles slot names for classes in documentation objects obtained
     by editing shells created by 'promptClass'.

     Help files named 'pkgname-defunct.Rd' for the appropriate pkgname
     are checked more loosely, as they may have undocumented arguments.

_V_a_l_u_e:

     'codoc' returns 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 'code' and
     'docs', giving the corresponding arguments obtained from the
     function's code and documented usage).

     'codocClasses' and 'codocData' return objects of class
     '"codocClasses"' and '"codocData"', respectively, with a structure
     similar to class '"codoc"'.

     There are 'print' methods for nicely displaying the information
     contained in such objects.

_W_a_r_n_i_n_g:

     Both 'codocClasses' and 'codocData' are still experimental. Names,
     interfaces and values might change in future versions.

_N_o_t_e:

     The default for 'use.values' has been changed from 'FALSE' to
     'NULL', for R versions 1.9.0 and later.

_S_e_e _A_l_s_o:

     'undoc', 'QC'