The R13B03 release.OTP_R13B03

1 files changed, 458 insertions, 0 deletions

diff --git a/lib/tools/doc/src/cover.xml b/lib/tools/doc/src/cover.xml
new file mode 100644
index 0000000000..323bd0dda8
--- /dev/null
+++ b/lib/tools/doc/src/cover.xml
@@ -0,0 +1,458 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2001</year>
+      <year>2007</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+  The contents of this file are subject to the Erlang Public License,
+  Version 1.1, (the "License"); you may not use this file except in
+  compliance with the License. You should have received a copy of the
+  Erlang Public License along with this software. If not, it can be
+  retrieved online at http://www.erlang.org/.
+
+  Software distributed under the License is distributed on an "AS IS"
+  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+  the License for the specific language governing rights and limitations
+  under the License.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>cover</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>cover</module>
+  <modulesummary>A Coverage Analysis Tool for Erlang</modulesummary>
+  <description>
+    <p>The module <c>cover</c> provides a set of functions for coverage
+      analysis of Erlang programs, counting how many times each
+      <em>executable line</em> of code is executed when a program is run.      <br></br>
+
+      An executable line contains an Erlang expression such as a matching
+      or a function call. A blank line or a line containing a comment,
+      function head or pattern in a <c>case</c>- or <c>receive</c> statement
+      is not executable.</p>
+    <p>Coverage analysis can be used to verify test cases, making sure all
+      relevant code is covered, and may also be helpful when looking for
+      bottlenecks in the code.</p>
+    <p>Before any analysis can take place, the involved modules must be
+      <em>Cover compiled</em>. This means that some extra information is
+      added to the module before it is compiled into a binary which then
+      is loaded. The source file of the module is not affected and no
+      <c>.beam</c> file is created.</p>
+    <p>Each time a function in a Cover compiled module is called,
+      information about the call is added to an internal database of Cover.
+      The coverage analysis is performed by examining the contents of
+      the Cover database. The output <c>Answer</c> is determined by two
+      parameters, <c>Level</c> and <c>Analysis</c>.</p>
+    <list type="bulleted">
+      <item>
+        <p><c>Level = module</c></p>
+        <p><c>Answer = {Module,Value}</c>, where <c>Module</c> is the module
+          name.</p>
+      </item>
+      <item>
+        <p><c>Level = function</c></p>
+        <p><c>Answer = [{Function,Value}]</c>, one tuple for each function in
+          the module. A function is specified by its module name <c>M</c>,
+          function name <c>F</c> and arity <c>A</c> as a tuple
+          <c>{M,F,A}</c>.</p>
+      </item>
+      <item>
+        <p><c>Level = clause</c></p>
+        <p><c>Answer = [{Clause,Value}]</c>, one tuple for each clause in
+          the module. A clause is specified by its module name <c>M</c>,
+          function name <c>F</c>, arity <c>A</c> and position in the function
+          definition <c>C</c> as a tuple <c>{M,F,A,C}</c>.</p>
+      </item>
+      <item>
+        <p><c>Level = line</c></p>
+        <p><c>Answer = [{Line,Value}]</c>, one tuple for each executable
+          line in the module. A line is specified by its module name <c>M</c>
+          and line number in the source file <c>N</c> as a tuple
+          <c>{M,N}</c>.</p>
+      </item>
+      <item>
+        <p><c>Analysis = coverage</c></p>
+        <p><c>Value = {Cov,NotCov}</c> where <c>Cov</c> is the number of
+          executable lines in the module, function, clause or line that have
+          been executed at least once and <c>NotCov</c> is the number of
+          executable lines that have not been executed.</p>
+      </item>
+      <item>
+        <p><c>Analysis = calls</c></p>
+        <p><c>Value = Calls</c> which is the number of times the module,
+          function, or clause has been called. In the case of line level
+          analysis, <c>Calls</c> is the number of times the line has been
+          executed.</p>
+      </item>
+    </list>
+    <p><em>Distribution</em></p>
+    <p>Cover can be used in a distributed Erlang system. One of the
+      nodes in the system must then be selected as the <em>main node</em>, and all Cover commands must be executed from this
+      node. The error reason <c>not_main_node</c> is returned if an
+      interface function is called on one of the remote nodes.</p>
+    <p>Use <c>cover:start/1</c> and <c>cover:stop/1</c> to add or
+      remove nodes. The same Cover compiled code will be loaded on each
+      node, and analysis will collect and sum up coverage data results
+      from all nodes.</p>
+  </description>
+  <funcs>
+    <func>
+      <name>start() -> {ok,Pid} | {error,Reason}</name>
+      <fsummary>Start Cover.</fsummary>
+      <type>
+        <v>Pid = pid()</v>
+        <v>Reason = {already_started,Pid}</v>
+      </type>
+      <desc>
+        <p>Starts the Cover server which owns the Cover internal database.
+          This function is called automatically by the other functions in
+          the module.</p>
+      </desc>
+    </func>
+    <func>
+      <name>start(Nodes) -> {ok,StartedNodes} | {error,not_main_node}</name>
+      <fsummary>Start Cover on remote nodes.</fsummary>
+      <type>
+        <v>Nodes = StartedNodes = [atom()]</v>
+      </type>
+      <desc>
+        <p>Starts a Cover server on the each of given nodes, and loads
+          all cover compiled modules.</p>
+      </desc>
+    </func>
+    <func>
+      <name>compile(ModFile) -> Result</name>
+      <name>compile(ModFile, Options) -> Result</name>
+      <name>compile_module(ModFile) -> Result</name>
+      <name>compile_module(ModFile, Options) -> Result</name>
+      <fsummary>Compile a module for Cover analysis.</fsummary>
+      <type>
+        <v>ModFile = Module | File</v>
+        <v>&nbsp;Module = atom()</v>
+        <v>&nbsp;File = string()</v>
+        <v>Options = [Option]</v>
+        <v>&nbsp;Option = {i,Dir} | {d,Macro} | {d,Macro,Value}</v>
+        <d>See <c>compile:file/2.</c></d>
+        <v>Result = {ok,Module} | {error,File} | {error,not_main_node}</v>
+      </type>
+      <desc>
+        <p>Compiles a module for Cover analysis. The module is given by its
+          module name <c>Module</c> or by its file name <c>File</c>.
+          The <c>.erl</c> extension may be omitted. If the module is
+          located in another directory, the path has to be specified.</p>
+        <p><c>Options</c> is a list of compiler options which defaults to
+          <c>[]</c>. Only options defining include file directories and
+          macros are passed to <c>compile:file/2</c>, everything else is
+          ignored.</p>
+        <p>If the module is successfully Cover compiled, the function
+          returns <c>{ok,Module}</c>. Otherwise the function returns
+          <c>{error,File}</c>. Errors and warnings are printed as they
+          occur.</p>
+        <p>Note that the internal database is (re-)initiated during
+          the compilation, meaning any previously collected coverage data
+          for the module will be lost.</p>
+      </desc>
+    </func>
+    <func>
+      <name>compile_directory() -> [Result] | {error,Reason}</name>
+      <name>compile_directory(Dir) -> [Result] | {error,Reason}</name>
+      <name>compile_directory(Dir, Options) -> [Result] | {error,Reason}</name>
+      <fsummary>Compile all modules in a directory for Cover analysis.</fsummary>
+      <type>
+        <v>Dir = string()</v>
+        <v>Options = [Option]</v>
+        <d>See <c>compile_module/1,2</c></d>
+        <v>Result = {ok,Module} | {error,File} | {error,not_main_node}</v>
+        <d>See <c>compile_module/1,2</c></d>
+        <v>Reason = eacces | enoent</v>
+      </type>
+      <desc>
+        <p>Compiles all modules (<c>.erl</c> files) in a directory
+          <c>Dir</c> for Cover analysis the same way as
+          <c>compile_module/1,2</c> and returns a list with the return
+          values.</p>
+        <p><c>Dir</c> defaults to the current working directory.</p>
+        <p>The function returns <c>{error,eacces}</c> if the directory is not
+          readable or <c>{error,enoent}</c> if the directory does not exist.</p>
+      </desc>
+    </func>
+    <func>
+      <name>compile_beam(ModFile) -> Result</name>
+      <fsummary>Compile a module for Cover analysis, using an existing beam.</fsummary>
+      <type>
+        <v>ModFile = Module | BeamFile</v>
+        <v>&nbsp;Module = atom()</v>
+        <v>&nbsp;BeamFile = string()</v>
+        <v>Result = {ok,Module} | {error,BeamFile} | {error,Reason}</v>
+        <v>&nbsp;Reason = non_existing | {no_abstract_code,BeamFile} | {encrypted_abstract_code,BeamFile} | {already_cover_compiled,no_beam_found,Module} | not_main_node</v>
+      </type>
+      <desc>
+        <p>Does the same as <c>compile/1,2</c>, but uses an existing
+          <c>.beam</c> file as base, i.e. the module is not compiled
+          from source. Thus <c>compile_beam/1</c> is faster than
+          <c>compile/1,2</c>.</p>
+        <p>Note that the existing <c>.beam</c> file must contain
+          <em>abstract code</em>, i.e. it must have been compiled with
+          the <c>debug_info</c> option. If not, the error reason
+          <c>{no_abstract_code,BeamFile}</c> is returned.
+          If the abstract code is encrypted, and no key is available
+          for decrypting it, the error reason 
+          <c><![CDATA[{encrypted_abstract_code,BeamFile} is returned. <p>If only the module name (i.e. not the full name of the <c>.beam]]></c> file) is given to this function, the
+          <c>.beam</c> file is found by calling
+          <c>code:which(Module)</c>. If no <c>.beam</c> file is found,
+          the error reason <c>non_existing</c> is returned. If the
+          module is already cover compiled with <c>compile_beam/1</c>,
+          the <c>.beam</c> file will be picked from the same location
+          as the first time it was compiled. If the module is already
+          cover compiled with <c>compile/1,2</c>, there is no way to
+          find the correct <c>.beam</c> file, so the error reason
+          <c>{already_cover_compiled,no_beam_found,Module}</c> is
+          returned.</p>
+        <p><c>{error,BeamFile}</c> is returned if the compiled code
+          can not be loaded on the node.</p>
+      </desc>
+    </func>
+    <func>
+      <name>compile_beam_directory() -> [Result] | {error,Reason}</name>
+      <name>compile_beam_directory(Dir) -> [Result] | {error,Reason}</name>
+      <fsummary>Compile all .beam files in a directory for Cover analysis.</fsummary>
+      <type>
+        <v>Dir = string()</v>
+        <v>Result = See compile_beam/1</v>
+        <v>Reason = eacces | enoent</v>
+      </type>
+      <desc>
+        <p>Compiles all modules (<c>.beam</c> files) in a directory
+          <c>Dir</c> for Cover analysis the same way as
+          <c>compile_beam/1</c> and returns a list with the return
+          values.</p>
+        <p><c>Dir</c> defaults to the current working directory.</p>
+        <p>The function returns <c>{error,eacces}</c> if the directory is not
+          readable or <c>{error,enoent}</c> if the directory does not exist.</p>
+      </desc>
+    </func>
+    <func>
+      <name>analyse(Module) -> {ok,Answer} | {error,Error}</name>
+      <name>analyse(Module, Analysis) -> {ok,Answer} | {error,Error}</name>
+      <name>analyse(Module, Level) -> {ok,Answer} | {error,Error}</name>
+      <name>analyse(Module, Analysis, Level) -> {ok,Answer} | {error,Error}</name>
+      <fsummary>Analyse a Cover compiled module.</fsummary>
+      <type>
+        <v>Module = atom()</v>
+        <v>Analysis = coverage | calls</v>
+        <v>Level = line | clause | function | module</v>
+        <v>Answer = {Module,Value} | [{Item,Value}]</v>
+        <v>&nbsp;Item = Line | Clause | Function</v>
+        <v>&nbsp;&nbsp;Line = {M,N}</v>
+        <v>&nbsp;&nbsp;Clause = {M,F,A,C}</v>
+        <v>&nbsp;&nbsp;Function = {M,F,A}</v>
+        <v>&nbsp;&nbsp;&nbsp;M = F = atom()</v>
+        <v>&nbsp;&nbsp;&nbsp;N = A = C = integer()</v>
+        <v>&nbsp;Value = {Cov,NotCov} | Calls</v>
+        <v>&nbsp;&nbsp;Cov = NotCov = Calls = integer()</v>
+        <v>Error = {not_cover_compiled,Module} | not_main_node</v>
+      </type>
+      <desc>
+        <p>Performs analysis of a Cover compiled module <c>Module</c>, as
+          specified by <c>Analysis</c> and <c>Level</c> (see above), by
+          examining the contents of the internal database.</p>
+        <p><c>Analysis</c> defaults to <c>coverage</c> and <c>Level</c>
+          defaults to <c>function</c>.</p>
+        <p>If <c>Module</c> is not Cover compiled, the function returns
+          <c>{error,{not_cover_compiled,Module}}</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>analyse_to_file(Module) -> </name>
+      <name>analyse_to_file(Module,Options) -> </name>
+      <name>analyse_to_file(Module, OutFile) -> </name>
+      <name>analyse_to_file(Module, OutFile, Options) ->  {ok,OutFile} | {error,Error}</name>
+      <fsummary>Detailed coverage analysis of a Cover compiled module.</fsummary>
+      <type>
+        <v>Module = atom()</v>
+        <v>OutFile = string()</v>
+        <v>Options = [Option]</v>
+        <v>Option = html</v>
+        <v>Error = {not_cover_compiled,Module} | {file,File,Reason} | no_source_code_found | not_main_node</v>
+        <v>&nbsp;File = string()</v>
+        <v>&nbsp;Reason = term()</v>
+      </type>
+      <desc>
+        <p>Makes a copy <c>OutFile</c> of the source file for a module
+          <c>Module</c>, where it for each executable line is specified
+          how many times it has been executed.</p>
+        <p>The output file <c>OutFile</c> defaults to
+          <c>Module.COVER.out</c>, or <c>Module.COVER.html</c> if the
+          option <c>html</c> was used.</p>
+        <p>If <c>Module</c> is not Cover compiled, the function returns
+          <c>{error,{not_cover_compiled,Module}}</c>.</p>
+        <p>If the source file and/or the output file cannot be opened using
+          <c>file:open/2</c>, the function returns
+          <c>{error,{file,File,Reason}}</c> where <c>File</c> is the file
+          name and <c>Reason</c> is the error reason.</p>
+        <p>If the module was cover compiled from the <c>.beam</c>
+          file, i.e. using <c>compile_beam/1</c> or
+          <c>compile_beam_directory/0,1</c>, it is assumed that the
+          source code can be found in the same directory as the
+          <c>.beam</c> file, or in <c>../src</c> relative to that
+          directory. If no source code is found, 
+          <c>,{error,no_source_code_found}</c> is returned.</p>
+      </desc>
+    </func>
+    <func>
+      <name>modules() -> [Module] | {error,not_main_node}</name>
+      <fsummary>Return all Cover compiled modules.</fsummary>
+      <type>
+        <v>Module = atom()</v>
+      </type>
+      <desc>
+        <p>Returns a list with all modules that are currently Cover
+          compiled.</p>
+      </desc>
+    </func>
+    <func>
+      <name>imported_modules() -> [Module] | {error,not_main_node}</name>
+      <fsummary>Return all modules for which there are imported data.</fsummary>
+      <type>
+        <v>Module = atom()</v>
+      </type>
+      <desc>
+        <p>Returns a list with all modules for which there are
+          imported data.</p>
+      </desc>
+    </func>
+    <func>
+      <name>imported() -> [File] | {error,not_main_node}</name>
+      <fsummary>Return all imported files.</fsummary>
+      <type>
+        <v>File = string()</v>
+      </type>
+      <desc>
+        <p>Returns a list with all imported files.</p>
+      </desc>
+    </func>
+    <func>
+      <name>which_nodes() -> [Node] | {error,not_main_node}</name>
+      <fsummary>Return all nodes that are part of the coverage analysis.</fsummary>
+      <type>
+        <v>Node = atom()</v>
+      </type>
+      <desc>
+        <p>Returns a list with all nodes that are part of the coverage
+          analysis. Note that the current node is not returned. This
+          node is always part of the analysis.</p>
+      </desc>
+    </func>
+    <func>
+      <name>is_compiled(Module) -> {file,File} | false |  {error,not_main_node}</name>
+      <fsummary>Check if a module is Cover compiled.</fsummary>
+      <type>
+        <v>Module = atom()</v>
+        <v>Beam = string()</v>
+      </type>
+      <desc>
+        <p>Returns <c>{file,File}</c> if the module <c>Module</c> is
+          Cover compiled, or <c>false</c> otherwise. <c>File</c> is
+          the <c>.erl</c> file used by <c>cover:compile_module/1,2</c>
+          or the <c>.beam</c> file used by <c>compile_beam/1</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>reset(Module) -></name>
+      <name>reset() ->  ok | {error,not_main_node}</name>
+      <fsummary>Reset coverage data for Cover compiled modules.</fsummary>
+      <type>
+        <v>Module = atom()</v>
+      </type>
+      <desc>
+        <p>Resets all coverage data for a Cover compiled module
+          <c>Module</c> in the Cover database on all nodes. If the
+          argument is omitted, the coverage data will be reset for all
+          modules known by Cover.</p>
+        <p>If <c>Module</c> is not Cover compiled, the function returns
+          <c>{error,{not_cover_compiled,Module}}</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>export(ExportFile)</name>
+      <name>export(ExportFile,Module) -> ok | {error,Reason}</name>
+      <fsummary>Reset coverage data for Cover compiled modules.</fsummary>
+      <type>
+        <v>ExportFile = string()</v>
+        <v>Module = atom()</v>
+        <v>Reason = {not_cover_compiled,Module} | {cant_open_file,ExportFile,Reason} | not_main_node</v>
+      </type>
+      <desc>
+        <p>Exports the current coverage data for <c>Module</c> to the
+          file <c>ExportFile</c>. It is recommended to name the
+          <c>ExportFile</c> with the extension <c>.coverdata</c>, since
+          other filenames can not be read by the web based interface to
+          cover.</p>
+        <p>If <c>Module</c> is not given, data for all Cover compiled
+          or earlier imported modules is exported.</p>
+        <p>This function is useful if coverage data from different
+          systems is to be merged.</p>
+        <p>See also <c>cover:import/1</c></p>
+      </desc>
+    </func>
+    <func>
+      <name>import(ExportFile) -> ok | {error,Reason}</name>
+      <fsummary>Reset coverage data for Cover compiled modules.</fsummary>
+      <type>
+        <v>ExportFile = string()</v>
+        <v>Reason = {cant_open_file,ExportFile,Reason} | not_main_node</v>
+      </type>
+      <desc>
+        <p>Imports coverage data from the file <c>ExportFile</c>
+          created with <c>cover:export/1,2</c>. Any analysis performed
+          after this will include the imported data.</p>
+        <p>Note that when compiling a module <em>all existing coverage data is removed</em>, including imported data. If a module is
+          already compiled when data is imported, the imported data is
+          <em>added</em> to the existing coverage data.</p>
+        <p>Coverage data from several export files can be imported
+          into one system. The coverage data is then added up when
+          analysing.</p>
+        <p>Coverage data for a module can not be imported from the
+          same file twice unless the module is first reset or
+          compiled. The check is based on the filename, so you can
+          easily fool the system by renaming your export file.</p>
+        <p>See also <c>cover:export/1,2</c></p>
+      </desc>
+    </func>
+    <func>
+      <name>stop() -> ok | {error,not_main_node}</name>
+      <fsummary>Stop Cover.</fsummary>
+      <desc>
+        <p>Stops the Cover server and unloads all Cover compiled code.</p>
+      </desc>
+    </func>
+    <func>
+      <name>stop(Nodes) -> ok | {error,not_main_node}</name>
+      <fsummary>Stop Cover on remote nodes.</fsummary>
+      <type>
+        <v>Nodes = [atom()]</v>
+      </type>
+      <desc>
+        <p>Stops the Cover server and unloads all Cover compiled code
+          on the given nodes. Data stored in the Cover database on the
+          remote nodes is fetched and stored on the main node.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p>code(3), compile(3)</p>
+  </section>
+</erlref>
+