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 usage of R
     function objects in a package, by comparing names and optionally
     also corresponding positions and default values of the arguments
     of the functions.

_U_s_a_g_e:

     codoc(package, dir, lib.loc = NULL,
           use.values = FALSE, use.positions = TRUE,
           ignore.generic.functions = FALSE,
           verbose = getOption("verbose"))

_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 to search for `package'.

use.positions: a logical indicating whether to use the positions of
          function arguments when comparing.

use.values: a logical indicating whether to use function default values
          when comparing code and docs.

ignore.generic.functions: if `TRUE', functions the body of which
          contains `"UseMethod"' are ignored.

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

_D_e_t_a_i_l_s:

     The purpose of this function 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 manipulated in order to
     give function stubs corresponding to the indicated usage, which
     are then sourced in another new environment.  For interpreted
     functions in both the code and docs environment, the formals are
     compared according to the values of the arguments `use.positions'
     and `use.values'.

     Currently, synopsis sections are used, but multiple usage examples
     (such as in `abline') are not combined when building the stubs. 
     Occurences of synopsis sections are reported if `verbose' is true.

_V_a_l_u_e:

     An object of class `"codoc"' which is a list the names of which
     are the names of the functions where an inconsistency was found. 
     The elements of the list are lists of length 2 with elements
     `code' and `docs', giving the corresponding arguments obtained
     from the function's code and documented usage.

     There is a `print' method for nicely displaying the information
     contained in such objects.

_S_e_e _A_l_s_o:

     `undoc'

