\Header{codoc}{Check Code/Documentation Consistency}
\keyword{documentation}{codoc}
\begin{Description}\relax
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.\end{Description}
\begin{Usage}
\begin{verbatim}
codoc(dir, use.values = FALSE, use.positions = TRUE,
      ignore.generic.functions = FALSE,
      keep.tempfiles = FALSE,
      verbose = getOption("verbose"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{dir}] a character string specifying the path to a package's root
source directory.  This must contain the subdirectories \file{man}
with \R{} documentation sources (in Rd format) and \file{R} with \R{}
code.
\item[\code{use.positions}] a logical indicating whether to use the positions
of function arguments when comparing.
\item[\code{use.values}] a logical indicating whether to use function default
values when comparing code and docs.
\item[\code{ignore.generic.functions}] if \code{TRUE}, functions the body of
which contains \code{"UseMethod"} are ignored.
\item[\code{keep.tempfiles}] if \code{TRUE}, keep temporary code and docs
files used for comparison.  This is useful for debugging.
\item[\code{verbose}] a logical.  If \code{TRUE}, additional diagnostics are
printed.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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 typically employs
the name of the generic rather than the method.

The following algorithm is used.  The \R{} code of the package is
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 \code{use.positions} and \code{use.values}.

Currently, synopsis sections are used, but multiple usage examples
(such as in \code{\Link{abline}}) are not combined when building the
stubs.\end{Details}
\begin{Value}
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{code} and \code{docs}, giving the corresponding
arguments obtained from the function's code and documented usage.\end{Value}
\begin{SeeAlso}\relax
\code{\Link{undoc}}\end{SeeAlso}

