Updated documentation.

mainline/doc/project.html

@@ -43,7 +43,7 @@ along with Metrix++. If not, see <http://www.gnu.org/licenses/>.
     </tr>
     <tr>
       <td><img src="logo_project.png" alt="Software Index Project Page" /></td>
-      <td valign="center">
+      <td valign="top">
         <div align="right">
         <p align="center"><a href="http://sourceforge.net/projects/swi"
         class="lowImportance"><img
@@ -203,11 +203,214 @@ along with Metrix++. If not, see <http://www.gnu.org/licenses/>.
 
                 <h4>Basic Workflow</h4>
 
-                <p>TBD</p>
+                <p>Assuming that you opened a terminal and your current working
+                directory is in the root folder of the tool installed.</p>
+
+                <p><strong>I.</strong> Start with running a collector tool,
+                enabling a collection of cyclomatic complexity:</p>
+
+                <p><pre>&gt; python <span class="highImportance">collect.py</span> <span class="normalImportance">--std.code.complexity.on</span> -- /path/to/your/project ../../path/to/some/other/project</pre>
+                </p>
+
+                <p>It will generate a database file in working directory with
+                default name. In order to change the name or location, use
+                corresponding command line option. Depending on a size of code
+                base, colection may take seconds or minutes, but it is very
+                fast in general. In order to achive the highest performance (~
+                to calculation of crc32) for iterative re-scans, point out to
+                the dabase file collected for the previous code revision:</p>
+
+                <p><pre>&gt; python <span class="highImportance">collect.py</span> --std.code.complexity.on <span class="highImportance normalImportance">--general.db-file-prev=metrixpp-prev.db</span> --
+ /path/to/your/project</pre>
+                </p>
+
+                <p>Paths are optional. If you do not specify a path, it will
+                scan files in current working directory. Check other available
+                options for the tool by executing:</p>
+
+                <p><pre>&gt; python <span class="highImportance">collect.py</span> <span class="normalImportance">--help</span></pre>
+                </p>
+
+                <p><strong>II.</strong> Secondly, export data using export
+                tool.</p>
+
+                <p><pre>&gt; python <span class="highImportance">export.py</span> --
+<span class="lowImportance">&lt;export&gt;
+    &lt;data&gt;
+        &lt;info path="" id="1" /&gt;
+        &lt;file-data /&gt;
+        &lt;subfiles&gt;
+        &lt;/subfiles&gt;
+        &lt;subdirs&gt;
+            &lt;subdir&gt;path&lt;/subdir&gt;
+        &lt;/subdirs&gt;
+        &lt;aggregated-data&gt;
+            &lt;<span class="normalImportance">std.code.complexity</span>&gt;
+                &lt;cyclomatic max="2" total="14.0" avg="0.168674698795" min="0" /&gt;
+            &lt;/<span class="normalImportance">std.code.complexity</span>&gt;
+            &lt;<span class="normalImportance">std.code.cpp</span>&gt;
+                &lt;files max="1" total="4.0" avg="1.0" min="1" /&gt;
+            &lt;/<span class="normalImportance">std.code.cpp</span>&gt;
+        &lt;/aggregated-data&gt;
+    &lt;/data&gt;
+&lt;/export&gt;</span>
+                </pre>
+                </p>
+
+                <p>By default, it exports all aggregated data for all files
+                scanned in xml format. It is possible to re-configure output
+                format to python or plain text. In order to narrow the scope,
+                specify a path to directory or a file. In order to export only
+                subset of metrics, specify them as well.</p>
+
+                <p><pre>&gt; python <span class="highImportance">export.py</span> --general.format=<span class="normalImportance">python</span> --general.namespaces=<span class="normalImportance">std.code.complexity</span> --
+ <span class="normalImportance">/path/to/your/project/subdir</span>
+<span class="lowImportance">&lt;export&gt;
+    ...
+&lt;/export&gt;</span></pre>
+                </p>
+
+                <p>If you have got results collected for previous version,
+                point out to the file using the corresponding option and the
+                tool will add diff data.</p>
+
+                <p><pre>&gt; python <span class="highImportance">export.py</span> --general.namespaces=<span class="normalImportance">std.code.complexity</span> --general.db-file-prev=<span class="normalImportance">metrixpp-prev.db</span> --
+<span class="lowImportance">&lt;export&gt;
+    &lt;data&gt;
+        &lt;info path="" id="1" /&gt;
+        &lt;file-data /&gt;
+        &lt;subfiles&gt;
+        &lt;/subfiles&gt;
+        &lt;subdirs&gt;
+            &lt;subdir&gt;path&lt;/subdir&gt;
+        &lt;/subdirs&gt;
+        &lt;aggregated-data&gt;
+            &lt;<span class="normalImportance">std.code.complexity</span>&gt;
+                &lt;cyclomatic max="2" total="14.0" avg="0.168674698795" min="0"&gt;
+                    &lt;<span class="normalImportance">__diff__ max="0" total="0.0" avg="0.0" min="0"</span> /&gt;
+                &lt;/cyclomatic&gt;
+            &lt;/<span class="normalImportance">std.code.complexity</span>&gt;
+        &lt;/aggregated-data&gt;
+    &lt;/data&gt;
+&lt;/export&gt;</span>
+                </pre>
+                </p>
+
+                <p>Check other available options for the tool by executing:</p>
+
+                <p><pre>&gt; python <span class="highImportance">export.py</span> <span class="normalImportance">--help</span></pre>
+                </p>
+
+                <p><strong>III.</strong> Finally, identify code regions which
+                exceed a specified limit, applying it to all scanned files:</p>
+
+                <p><pre>&gt; python <span class="highImportance">limit.py</span> --general.max-limit=<span class="normalImportance">std.code.complexity</span><strong>:</strong><span class="normalImportance">cyclomatic</span><strong>:</strong><span class="normalImportance">7</span><strong> </strong>--
+<span class="lowImportance">/path/to/your/project/ui/notifications.cpp:72: warning: Metric '<span class="normalImportance">std.code.complexity</span>/<span class="normalImportance">cyclomatic</span>' for
+ region 'doFont' exceeds the limit.
+        Metric name    : <span class="normalImportance">std.code.complexity</span>/<span class="normalImportance">cyclomatic</span>
+        Region name    : doFont
+        Metric value   : 10
+        Modified       : None
+        Change trend   : None
+        Limit          : 7
+/path/to/your/project/ui/notifications.cpp:144: warning: Metric '<span class="normalImportance">std.code.complexity</span>/<span class="normalImportance">cyclomatic</span>' for
+ region 'doStyle' exceeds the limit.
+        Metric name    : <span class="normalImportance">std.code.complexity</span>/<span class="normalImportance">cyclomatic</span>
+        Region name    : doStyle
+        Metric value   : 9
+        Modified       : None
+        Change trend   : None
+        Limit          : 7</span></pre>
+                </p>
+
+                <p>You can limit the scope of analysis by defining paths to
+                directories or files.If you have got results collected for
+                previous version, point out to the file using the corresponding
+                option and the tool will notify about change status:</p>
+
+                <p><pre>&gt; python <span class="highImportance">limit.py</span> --general.max-limit=std.code.complexity<strong>:</strong>cyclomatic<strong>:</strong>7
+ --general.db-file-prev=<span class="normalImportance">metrixpp-prev.db</span> --
+<span class="lowImportance normalImportance">/path/to/your/project/ui/notifications.cpp:72: warning: Metric 'std.code.complexity/cyclomatic' for
+ region 'doFont' exceeds the limit.
+        Metric name    : std.code.complexity/cyclomatic
+        Region name    : doFont
+        Metric value   : 10
+        Modified       : <span class="normalImportance">True</span>
+        Change trend   : <span class="normalImportance">0</span>
+        Limit          : 7
+/path/to/your/project/ui/notifications.cpp:144: warning: Metric 'std.code.complexity/cyclomatic' for
+ region 'doStyle' exceeds the limit.
+        Metric name    : std.code.complexity/cyclomatic
+        Region name    : doStyle
+        Metric value   : 9
+        Modified       : <span class="normalImportance">True</span>
+        Change trend   : <span class="normalImportance">+1</span>
+        Limit          : 7</span></pre>
+                </p>
+
+                <p>Another useful option for this tool helps you to <span
+                class="highImportance">deal with legacy code</span>. It is not
+                unusual if you have got enormous number of warnings enabling
+                new thresholds for the code designed in the past, which has not
+                be profiled/targeted to specific metric limits. By default the
+                tool warns about all code regions, ignoring their change
+                status. You can reconfigure it to one of the following:</p>
+                <ul>
+                  <li>warn only about <span class="normalImportance">new</span>
+                    code regions (functions, classes):</li>
+                </ul>
 
-                <h4>Dealing Legacy Code</h4>
+                <p><pre>&gt; python <span class="highImportance">limit.py</span> --general.max-limit=std.code.complexity<strong>:</strong>cyclomatic<strong>:</strong>7
+ --general.db-file-prev=metrixpp-prev.db <span class="normalImportance">--general.warn=<strong>new</strong></span> --</pre>
+                </p>
+                <ul>
+                  <li>warn about <span class="normalImportance">new</span> code
+                    regions and <span class="normalImportance">modifed regions
+                    <strong>regressing</strong> the metric</span> (enforces the
+                    rule 'leave not worse than it was before'):</li>
+                </ul>
+
+                <p><pre>&gt; python <span class="highImportance">limit.py</span> --general.max-limit=std.code.complexity<strong>:</strong>cyclomatic<strong>:</strong>7
+ --general.db-file-prev=metrixpp-prev.db <span class="normalImportance">--general.warn=<strong>trend</strong></span> --
+<span class="lowImportance normalImportance">/path/to/your/project/ui/notifications.cpp:144: warning: Metric 'std.code.complexity/cyclomatic' for
+ region 'doStyle' exceeds the limit.
+        Metric name    : std.code.complexity/cyclomatic
+        Region name    : doStyle
+        Metric value   : 9
+        Modified       : <span class="normalImportance">True</span>
+        Change trend   : <span class="normalImportance"><strong>+1</strong></span>
+        Limit          : 7</span></pre>
+                </p>
+                <ul>
+                  <li>warn about <span class="normalImportance">new</span> and
+                    <span class="normalImportance">all modified regions</span>
+                    (motivates for refactoring of legacy code): </li>
+                </ul>
 
-                <p>TBD</p>
+                <p><pre>&gt; python <span class="highImportance">limit.py</span> --general.max-limit=std.code.complexity<strong>:</strong>cyclomatic<strong>:</strong>7
+ --general.db-file-prev=metrixpp-prev.db <span class="normalImportance">--general.warn=<strong>touched</strong></span> --
+<span class="lowImportance normalImportance">/path/to/your/project/ui/notifications.cpp:72: warning: Metric 'std.code.complexity/cyclomatic' for
+ region 'doFont' exceeds the limit.
+        Metric name    : std.code.complexity/cyclomatic
+        Region name    : doFont
+        Metric value   : 10
+        Modified       : <span class="normalImportance"><strong>True</strong></span>
+        Change trend   : <span class="normalImportance">0</span>
+        Limit          : 7
+/path/to/your/project/ui/notifications.cpp:144: warning: Metric 'std.code.complexity/cyclomatic' for
+ region 'doStyle' exceeds the limit.
+        Metric name    : std.code.complexity/cyclomatic
+        Region name    : doStyle
+        Metric value   : 9
+        Modified       : <strong><span class="normalImportance">True</span></strong>
+        Change trend   : <span class="normalImportance">+1</span>
+        Limit          : 7</span></pre>
+                </p>
+
+                <p>Check other available options for the tool by executing:</p>
+
+                <p><pre>&gt; python <span class="highImportance">limit.py</span> <span class="normalImportance">--help</span></pre>
+                </p>
 
                 <h3 id="Support">Bug Report &amp; Feature Request</h3>
 
@@ -227,15 +430,51 @@ along with Metrix++. If not, see <http://www.gnu.org/licenses/>.
 
                 <h4>New Metric</h4>
 
-                <p>TBD</p>
+                <p>Unfortunately, there is no rich documentation at this stage.
+                Briefly, any new plugin starts with creating 2 new files: 'ini'
+                and 'py'. You can copy from other avaialble (for example, <a
+                href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/ext/std/code/complexity.ini">ini</a>
+                and <a
+                href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/ext/std/code/complexity.py">py</a>
+                files for the standard complexity plugin) and impelement the
+                logic related to the new metric.</p>
 
                 <h4>New Analysis Tool</h4>
 
-                <p>TBD</p>
+                <p>Unfortunately, there is no rich documentation at this stage.
+                Briefly, database API (class Loader implemented in '<a
+                href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/core/db/loader.py">core.db.loader</a>')
+                is a starting point for any new post-analysis tool. There are 2
+                standard tools (<a
+                href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/export.py">export.py</a>
+                and <a
+                href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/limit.py">limit.py</a>)
+                available which use this API.</p>
 
                 <h4>New Language Support</h4>
 
-                <p>TBD</p>
+                <p>Unfortunately, there is no rich documentation at this stage.
+                Briefly:</p>
+                <ul>
+                  <li>a plugin is registered in the same way as a plugin for
+                    new metric</li>
+                  <li>it subscribes to directory reader plugin</li>
+                  <li>parses a file in a callback, called by directory
+                  reader</li>
+                  <li>parser needs to identify markers (like comments, strings,
+                    preprocessor) and regions (like functions, classes, etc.)
+                    and tell about this to file data object passed as an
+                    argument for the callback.</li>
+                </ul>
+
+                <p>Parser for C/C++ language can serve as <a
+                href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/ext/std/code/cpp.py">an
+                example</a>.</p>
+
+                <p>Finally, if there are any questions or enquires, please,
+                feel free to contact <a
+                href="mailto:avkonst@users.sourceforge.net">project
+                administrator</a> by e-mail.</p>
 
                 <h4>Source Code Repository</h4>
 

mainline/doc/style.css

@@ -31,6 +31,7 @@ body{
 pre{
     font-size: 100%;
     padding-left: 50px;
+    font-family:Courier;
 }
 
 td{