Coverage: add documentation 08/17808/3
Clément DAVID [Fri, 19 Feb 2016 14:13:59 +0000 (15:13 +0100)]
Change-Id: Ibb1f7e1d31c5a1be522072c6225646c817cd3de7

scilab/modules/coverage/help/en_US/addchapter.sce [new file with mode: 0644]
scilab/modules/coverage/help/en_US/covMerge.xml [new file with mode: 0644]
scilab/modules/coverage/help/en_US/covStart.xml [new file with mode: 0644]
scilab/modules/coverage/help/en_US/covStop.xml [new file with mode: 0644]
scilab/modules/coverage/help/en_US/covWrite.xml [new file with mode: 0644]

diff --git a/scilab/modules/coverage/help/en_US/addchapter.sce b/scilab/modules/coverage/help/en_US/addchapter.sce
new file mode 100644 (file)
index 0000000..a1f7c2e
--- /dev/null
@@ -0,0 +1,12 @@
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+// Copyright (C) 2012 - 2016 - Scilab Enterprises
+//
+// This file is hereby licensed under the terms of the GNU GPL v2.0,
+// pursuant to article 5.3.4 of the CeCILL v.2.1.
+// This file was originally licensed under the terms of the CeCILL v2.1,
+// and continues to be available under such terms.
+// For more information, see the COPYING file which you should have received
+// along with this program.
+
+add_help_chapter("Scilab code coverage",SCI+"/modules/coverage/help/en_US",%T);
+
diff --git a/scilab/modules/coverage/help/en_US/covMerge.xml b/scilab/modules/coverage/help/en_US/covMerge.xml
new file mode 100644 (file)
index 0000000..05db6f2
--- /dev/null
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="covMerge">
+    <refnamediv>
+        <refname>covMerge</refname>
+        <refpurpose>Merges coverage results and exports to a file</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>covMerge(binaryFiles, binaryFile)</synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>binaryFiles</term>
+                <listitem>
+                    <para>a set of coverage binary files</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>binaryFile</term>
+                <listitem>
+                    <para>a binary file</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    
+    <refsection>
+        <title>Description</title>
+        <para>
+            This command is used to merge coverage results and export them to a single file. It is used for in-depth analysis for a set of functions and runs. This will output only the results for the passed paths.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example"><![CDATA[
+covStart(isempty)
+for i=1:1e5; isempty(i); end
+covWrite("binary", "TMPDIR/isempty1")  // write runtime information
+covStop();                             // clear instrumentation
+
+covStart(isempty)
+for i=1:1e5; isempty(string(i)); end
+covWrite("binary", "TMPDIR/isempty2")  // write other runtime information
+covStop();
+
+covMerge(["TMPDIR/isempty1" "TMPDIR/isempty2"], "TMPDIR/isempty") // merge them
+covWrite("html", "TMPDIR/isempty", "TMPDIR/coverage") // render the information as HTML
+    ]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="covStart">covStart</link>
+            </member>
+            <member>
+                <link linkend="covStop">covStop</link>
+            </member>
+            <member>
+                <link linkend="covWrite">covWrite</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
+
diff --git a/scilab/modules/coverage/help/en_US/covStart.xml b/scilab/modules/coverage/help/en_US/covStart.xml
new file mode 100644 (file)
index 0000000..aa42a2d
--- /dev/null
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="covStart">
+    <refnamediv>
+        <refname>covStart</refname>
+        <refpurpose>Instruments some macros to store runtime information on code coverage and execution time</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>covStart(paths)</synopsis>
+        <synopsis>covStart(lib)</synopsis>
+        <synopsis>covStart([path ; lib])</synopsis>
+        <synopsis>covStart(macro)</synopsis>
+        <synopsis>covStart("all")</synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>paths</term>
+                <listitem>
+                    <para>string paths to identify macros</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>lib</term>
+                <listitem>
+                    <para>a library or a string which is a library name</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>macro</term>
+                <listitem>
+                    <para>a specific function (as a string name or a function value)</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>"all"</term>
+                <listitem>
+                    <para>special argument to instrument all the loaded macros</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            Instruments the passed arguments to store runtime informations on execution. These informations can be latter exported by calling <literal>covWrite</literal>. To remove any instrumentation data <literal>covStop</literal> can be used.
+        </para>
+        <para>
+            You can either select a set of function or all the available one on a specific call. The <literal>"all"</literal> analysis is useful to have a global overview and later specific informations can be produced for one or a set of identified functions.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+covStart(isempty)                      // instrument isempty by macro value
+for i=1:1e5; isempty(i); end           // run
+covWrite("html", "TMPDIR/coverage")    // write runtime information to a directory
+covStop();                             // remove any instrumentation
+    ]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="covStop">covStop</link>
+            </member>
+            <member>
+                <link linkend="covWrite">covWrite</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
+
diff --git a/scilab/modules/coverage/help/en_US/covStop.xml b/scilab/modules/coverage/help/en_US/covStop.xml
new file mode 100644 (file)
index 0000000..78e5767
--- /dev/null
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="covStop">
+    <refnamediv>
+        <refname>covStop</refname>
+        <refpurpose>Removes all instrumentation data</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>covStop()</synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Description</title>
+        <para>
+            Remove the instrumentation data and stop recording future execution. All the recording intiated by <literal>covStart</literal> will be canceled.
+        </para>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="covStart">covStart</link>
+            </member>
+            <member>
+                <link linkend="covWrite">covWrite</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
+
diff --git a/scilab/modules/coverage/help/en_US/covWrite.xml b/scilab/modules/coverage/help/en_US/covWrite.xml
new file mode 100644 (file)
index 0000000..599831b
--- /dev/null
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="covWrite">
+    <refnamediv>
+        <refname>covWrite</refname>
+        <refpurpose>Exports runtime information to files</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>covWrite("html", dir)</synopsis>
+        <synopsis>covWrite("binary", binaryFile)</synopsis>
+        <synopsis>covWrite("html", binaryFile, dir)</synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>"html"</term>
+                <listitem>
+                    <para>exports the coverage data as HTML files</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>"binary"</term>
+                <listitem>
+                    <para>store the coverage data as binary for later use</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>dir</term>
+                <listitem>
+                    <para>output directory as a string</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>binaryFile</term>
+                <listitem>
+                    <para>stored binary filename as a string</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            This command is used to export, store or "load and export" runtime instrumentation data to the file system. The major usage is to export the current runtime information to HTML files on a directory using <literal>covWrite("html", "TMPDIR/coverage")</literal>.
+        </para>
+        <para>
+            This command is used to export, store or "load and export" runtime instrumentation data to the file system.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Basic example</title>
+        <programlisting role="example"><![CDATA[
+covStart(isempty)                      // instrument isempty by macro value
+for i=1:1e5; isempty(i); end           // run
+covWrite("html", "TMPDIR/coverage")    // write runtime information to a directory
+covStop();                             // remove any instrumentation
+    ]]></programlisting>
+    </refsection>
+    <refsection>
+        <title>Binary exemple</title>
+        <programlisting role="example"><![CDATA[
+covStart(isempty)
+for i=1:1e5; isempty(i); end
+covWrite("binary", "TMPDIR/isempty1")  // write runtime information
+covStop();                             // clear instrumentation
+
+covStart(isempty)
+for i=1:1e5; isempty(string(i)); end
+covWrite("binary", "TMPDIR/isempty2")  // write other runtime information
+covStop();
+
+covMerge(["TMPDIR/isempty1" "TMPDIR/isempty2"], "TMPDIR/isempty") // merge them
+covWrite("html", "TMPDIR/isempty", "TMPDIR/coverage") // render the information as HTML
+    ]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="covStart">covStart</link>
+            </member>
+            <member>
+                <link linkend="covStop">covStop</link>
+            </member>
+            <member>
+                <link linkend="covMerge">covMerge</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
+