% Generated by roxygen2 (4.1.0): do not edit by hand
% Please edit documentation in R/coverage.r
\name{MeasureCoverage}
\alias{MeasureCoverage}
\title{Coverage Report on Specified R Virtual Machine Source Code}
\usage{
MeasureCoverage(root, verbose = TRUE, exclude.header = TRUE,
  file.detail = FALSE, func.detail = FALSE, file.keyword = "",
  func.keyword = "", ignore.case = TRUE)
}
\arguments{
\item{root}{a directory or a single C file that contains or is instrumented VM source.}

\item{verbose}{wheather to display resulting info}

\item{exclude.header}{whether to include header files in statistics.}

\item{file.detail}{whether to display statistic details for files. Only works if verbose is true.}

\item{func.detail}{whether to display statistic details for functions. Only works if verbose is true.}

\item{file.keyword}{filtering the result by only including files whose names contain the keyword.}

\item{func.keyword}{filtering the result by only including functions whose names contain the keyword.}

\item{ignore.case}{whether the keywords should be case-sensitive.}
}
\value{
list(file=file.df, func=func.df)
}
\description{
This function works with the GNU coverage tool, gcov, to report code coverage of the
 tested R virtual machine. and The VM must have been compiled with gcov support and executed at least
 once before this function is executed for meanful statistics. Note that, gcov is designed such
 that the coverage results are accumulated, so for a fresh new result of a test suit, call
 \code{\link{reset}} before executing the test suite. The coverage granularition spans line, function,
 and file.
}
\details{
In this section we give some design thoughts then in example section some sample
 reports and the interpretation.

 As a testcase contributor, the right way to use the coverage rate is to look for increments
 after new testcases are added rather than aiming for 100% coverage. The reason is that, due
 to the file inclusion feature of C language, exhaustive tests will be hardly shown as 100%
 coverage (could be lower or higher). Specifically, if one piece of code in a header file gets
 included in two C files, gcov reports it twice and C in C inclusion will make the situation
 even more complicated. So we give users the choices to either include both (over estimation)
 or include none (under estimation) in the overall result by allowing them to choose whether
 to include the header files in the statistics. Identifying duplication is almost impossible.

 On the other hand, gcov produces precise result object-wise. The term "object" is used as is
 in "object file" during linking, referring to a group of files glued together by inclusion,
 usually a C file and several header files but in rare case several C files and several header
 files. The coverage within the range of object is precise as C compilers guarantee no duplication
 by nature. In that, the object information is included in the file/function detail tables for
 users' reference.
}
\examples{
\dontrun{
MeasureCoverage()
}
}

