Improved documentation

mainline/doc/home.html

@@ -60,9 +60,6 @@
               <li class="">
                 <a href="./index.html">Home</a>
               </li>
-              <li class="">
-                <a href="./customize.html"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=275605&amp;type=10" alt="Get Software Index at SourceForge.net. Fast, secure and Free Open Source software downloads" border="0"></a>
-              </li>
             </ul>
           </div>
         </div>
@@ -425,7 +422,7 @@ file: __global__: comment
         </section>
         <section id="workflow_view_summary_section">
           <h3>Summary metrics and distribution tables/graphs</h3>
-          <p>It is time to look at the data. The command:</p>
+          <p>It is time to look at the data files collected (step above). The command:</p>
           <pre>
 &gt; python "/path/to/metrix++.py" view --db-file=boost_1_54_0/metrixpp.db
 </pre>
@@ -650,7 +647,7 @@ file: __global__: comment
           	in xml pr python disctionary formats. This can be particularly useful for integration of the tool with
           	other applications. For example, an editor may re-collect and show context based metrics when a file is saved.</p>
           <pre>
-&gt; python "/path/to/metrix++.py" view --format=xml
+&gt; python "/path/to/metrix++.py" view --db-file=boost_1_54_0/metrixpp.db --format=xml
 </pre>
           <p>Check other options of the view tool by executing:</p>
           <pre>
@@ -659,21 +656,281 @@ file: __global__: comment
         </section>
         <section id="workflow_limit_section">
           <h2>Apply thresholds</h2>
-          <p>...</p>
+          <p>The viewer shows (above) that there are function with quite large value of cyclomatic complexity metric.
+          	 Growth of this metric can be considered as negative trend. Metrix++ 'limit' tool offers the capability
+          	 to organise the control over trends by applying limits to metric values.
+          	 Exceeded limites are alarms in the quality management and control.</p>
         </section>
         <section id="workflow_limit_hotspots_section">
-          <h3>Suppressions</h3>
-          <p>Metrix++ has got suppressions capability. Suppressions are collected from comments in code
-             and used by post-processing tools, like 'limit'. It allows to take fine grained control
-             over false-positive warnings, if there are.</p>
+          <h3>Hotspots</h3>
+          <p>Hotspots mode of the limit tool helps to identify top files/regions exceeding a metric threshold.
+          	Let's identify top 3 functions in boost interprocess library, which exceed limit of 15 points of
+          	cyclomatic complexity metric:</p>
+          <pre>
+&gt; python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15 --hotspots=3
+</pre>
+          <pre>
+./interprocess/detail/managed_open_or_create_impl.hpp:302: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_open_or_create' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : priv_open_or_create
+	Metric value   : 37
+	Modified       : None
+	Change trend   : None
+	Limit          : 15.0
+	Suppressed     : False
+
+./interprocess/streams/vectorstream.hpp:284: warning: Metric 'std.code.complexity:cyclomatic' for region 'seekoff' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : seekoff
+	Metric value   : 25
+	Modified       : None
+	Change trend   : None
+	Limit          : 15.0
+	Suppressed     : False
+
+./interprocess/streams/bufferstream.hpp:174: warning: Metric 'std.code.complexity:cyclomatic' for region 'seekoff' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : seekoff
+	Metric value   : 23
+	Modified       : None
+	Change trend   : None
+	Limit          : 15.0
+	Suppressed     : False
+</pre>
         </section>
         <section id="workflow_limit_control_section">
-          <h3>Suppressions</h3>
-          <p>Metrix++ has got suppressions capability. Suppressions are collected from comments in code
-             and used by post-processing tools, like 'limit'. It allows to take fine grained control
-             over false-positive warnings, if there are.</p>
+          <h3>Controlling trends</h3>
+          <p>Exit code of the 'limit' tool is equal to number of warnings printed. This allows to use the tool
+          	as a static analysis tool during software build process. In this case, non-zero exit code means
+          	that there are violations to the agreed standards and it may fail the build. So, the same command
+          	without --hotspots option will print all regions/files exceeding the specified limit:</p>
+          <pre>
+&gt; python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15
+</pre>
+          <h4>Modes to exclude old code from the considiration</h4>
+          <p>However, it is likely there are many warnings printed in this mode, especially if very old or legacy code is profiled 
+          	against new metrics and coding rules. Although all warnings can be removed 
+          	by re-factoring in scope of big task force activity, it is where many tools are rejected,
+          	because it is difficult to justify the initial cost of applying and integrating them.
+          	Metrix++ 'limit' tool has got an option --warn-mode, which helps to overcome this problem.</p>
+          <p>--warn-mode=touched encourages re-factoring only for new and modified regions. It enables
+          	continuous refactoring. It does not matter how late the rule is applied or 
+          	coding standard is modified. It is possible to do it anytime with zero initial investment.
+          	For example, applying it to boost interprocess library for a changes between 1.52 and 1.54 versions
+          	results in only 6 warnings:</p>
+          <pre>
+&gt; python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --db-file-prev=boost_1_52_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15 --warn-mode=touched
+</pre>
+          <pre>
+./interprocess/detail/managed_open_or_create_impl.hpp:302: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_open_or_create' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : priv_open_or_create
+	Metric value   : 37
+	Modified       : True
+	Change trend   : +1
+	Limit          : 15.0
+	Suppressed     : False
+
+./interprocess/ipc/message_queue.hpp:375: warning: Metric 'std.code.complexity:cyclomatic' for region 'insert_at' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : insert_at
+	Metric value   : 16
+	Modified       : True
+	Change trend   : 0
+	Limit          : 15.0
+	Suppressed     : False
+
+./interprocess/mapped_region.hpp:575: warning: Metric 'std.code.complexity:cyclomatic' for region 'mapped_region' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : mapped_region
+	Metric value   : 18
+	Modified       : True
+	Change trend   : +2
+	Limit          : 15.0
+	Suppressed     : False
+
+./interprocess/mem_algo/detail/mem_algo_common.hpp:452: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_allocate_many' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : priv_allocate_many
+	Metric value   : 20
+	Modified       : True
+	Change trend   : 0
+	Limit          : 15.0
+	Suppressed     : False
+
+./interprocess/mem_algo/rbtree_best_fit.hpp:787: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_expand_both_sides' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : priv_expand_both_sides
+	Metric value   : 17
+	Modified       : True
+	Change trend   : 0
+	Limit          : 15.0
+	Suppressed     : False
+
+./interprocess/sync/windows/named_sync.hpp:98: warning: Metric 'std.code.complexity:cyclomatic' for region 'open_or_create' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : open_or_create
+	Metric value   : 18
+	Modified       : True
+	Change trend   : 0
+	Limit          : 15.0
+	Suppressed     : False
+</pre>
+          <p>If it is challenging or not beneficial to refactor everything touched, 
+          	--warn-mode=trends simplifies the control over modified regions and only makes sure
+          	that there are no regressions in modified code. In other words, a warning is printed about modified region/file
+          	only if a metric exceeds the specified limit and the value of the metric has got negative trend in modification.
+          	It is possible to apply it anytime with zero initial investment and almost zero on-going investment around old code.
+          	For example, applying it to boost interprocess library for a changes between 1.52 and 1.54 versions
+          	results in only 2 warnings:</p>
+          <pre>
+&gt; python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --db-file-prev=boost_1_52_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15 --warn-mode=trend
+</pre>
+          <pre>
+./interprocess/detail/managed_open_or_create_impl.hpp:302: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_open_or_create' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : priv_open_or_create
+	Metric value   : 37
+	Modified       : True
+	Change trend   : +1
+	Limit          : 15.0
+	Suppressed     : False
+
+./interprocess/mapped_region.hpp:575: warning: Metric 'std.code.complexity:cyclomatic' for region 'mapped_region' exceeds the limit.
+	Metric name    : std.code.complexity:cyclomatic
+	Region name    : mapped_region
+	Metric value   : 18
+	Modified       : True
+	Change trend   : +2
+	Limit          : 15.0
+	Suppressed     : False
+</pre>
+          <p>--warn-mode=new drops control over existing code and ensures that warnings are only about new code.
+          	For example, applying it to boost interprocess library for a changes between 1.52 and 1.54 versions
+          	results in 0 warnings, so new code is totally compliant with the standard required in the example.</p>
+          <pre>
+&gt; python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --db-file-prev=boost_1_52_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15 --warn-mode=new
+</pre>
+          <h4>Suppressions</h4>
+          <p>It is possible to suppress warnings on exceptional basis. Suppressions are collected from comments in code
+             and used by the 'limit' tool to filter out unnecessary (suppressed) warnings.
+             It allows to take fine grained control over false-positive warnings, if there are.</p>
+          <p>In order to suppress a warning:</p>
+          <ul>
+          	<li>per region metrics: put the metrix++ instruction in the comments before the region, for example:</li>
+          <pre class="prettyprint linenums">
+// This function returns string typed
+// representation of a name of a color,
+// requested by color's id
+// metrix++: suppress std.code.complexity:cyclomatic
+std::string getColorName(int color_id)
+{
+	switch (color_id)
+	{
+	case COLOR_RED:
+		return std::string("red")
+	case COLOR_GREEN:
+		return std::string("green")
+	case COLOR_BLUE:
+		return std::string("blue")
+	/* and so on */
+	}
+}
+</pre>
+          	<li>per file metrics: put the metrix++ instruction in the comments at the beginning of a file, for example:</li>
+          <pre class="prettyprint linenums">
+//
+// This file does processing of colors and brushes
+// Copyright is my company, 2013
+// 
+// However, it is too long and big file, and there is no time
+// to split it into multiple file, so shut up the metrix++ warnings:
+// metrix++: suppress std.general:size
+//
+
+std::string getColorName(int color_id)
+{
+	...
+...
+</pre>
+          	<li>activate collection of suppressions:</li>
+          <pre>
+&gt; python "/path/to/metrix++.py" collect --std.suppress
+</pre>
+          	<li>run the 'limit' tool WITHOUT --disable-suppressions option:</li>
+          <pre>
+&gt; python "/path/to/metrix++.py" limit ...
+</pre>
+             </ul>
+          <h5>Important notice:</h5>
+             <ul><li>--std.suppress option enables collection of 2 metrics as well: 'std.suppress:count' and 
+                'std.suppress.file:count'. The first is number of suppressions per region.
+                The second is the same but applies to file-scope metrics.
+                It allows to manage the amount of suppressions.
+                Usually there are no false-positives to suppress with the <strong>right</strong> metric,
+                but could be exceptions in specific cases. Managing suppressions is about managing exceptions.
+                If there are many exceptional cases, maybe something is wrong with a metric or an application of a metric.
+                Two code examples about colors above do not demonstrate the technically exceptional case,
+                they likely demonstrate a case of a process exception, like "there is no time to do it proper now", or
+                a case of wrong application of a metric, like "shut up the useless tool". So, be careful.
+                The 'view' tool shows number of suppressions and its change trends on per metric basis.</li></ul>
         </section>
 
+        <section id="workflow_other_section">
+          <h2>Other applications</h2>
+          <h3>Checking data file properties</h3>
+          <p>Metrix++ 'info' tool is helpful to check properties of a data file, like settings used to write it,  
+          	colected metrics and files processed. For example:</p>
+          <pre>
+&gt; python "/path/to/metrix++.py" info --db-file=boost_1_54_0/metrixpp.db
+</pre>
+          <pre>
+boost_1_54_0/metrixpp.db:: info: Created using plugins and settings:
+	version        : 1.0
+	std.code.complexity:version: 1.1
+	std.code.cpp:version: 1.1
+	std.code.cpp:files: *.c,*.cc,*.cpp,*.cxx,*.h,*.hh,*.hpp,*.hxx
+	std.code.cs:version: 1.0
+	std.code.cs:files: *.cs
+	std.code.java:version: 1.1
+	std.code.java:files: *.java
+	std.code.lines:version: 1.1
+
+test_workflow.db:: info: Collected metrics:
+	std.code.complexity:cyclomatic: 
+	std.code.lines:code: 
+
+:: info: Processed files and checksums:
+	./interprocess/allocators/detail/node_pool.hpp: 0xb099a7c3
+	./interprocess/allocators/detail/node_tools.hpp: 0xaaf5044d
+	./interprocess/anonymous_shared_memory.hpp: 0x2bf06cb0
+	./interprocess/containers/allocation_type.hpp: 0x8e95cda0
+	./interprocess/containers/containers_fwd.hpp: 0xa4d0d9f7
+	./interprocess/containers/deque.hpp: 0x6dbb77af
+	./interprocess/containers/flat_map.hpp: 0x6750338c
+	...
+</pre>
+          <h3>Exporting results</h3>
+          <p>Metrix++ 'export' tool exports data files to csv formated files. For example:</p>
+          <pre>
+&gt; python "/path/to/metrix++.py" export --db-file=boost_1_54_0/metrixpp.db > boost_1_54_0/metrixpp.csv
+</pre>
+          <pre>
+file,region,type,modified,line start,line end,std.code.complexity:cyclomatic,std.code.lines:code
+./interprocess/allocators/detail/node_pool.hpp,__global__,global,,1,110,,0
+./interprocess/allocators/detail/node_pool.hpp,boost,namespace,,33,105,,2
+./interprocess/allocators/detail/node_pool.hpp,interprocess,namespace,,34,104,,2
+./interprocess/allocators/detail/node_pool.hpp,ipcdetail,namespace,,35,103,,4
+./interprocess/allocators/detail/node_pool.hpp,SegmentManager,class,,39,72,,16
+...
+</pre>
+          <p>Files with csv format can be opened by applications, like Microsoft Office Excel, with advanced analysis capabilities.
+          	For example, to draw this distribution graph:</p>
+          <p align="center"><img src="assets/img/piechart.png"/></p>
+          <p>It is not recommended to use export tool to implement custom post-analysis Metrix++ extensions.
+          	  The main reason is non granted backward compatibility support for csv columns. Another main reason is that
+          	  exporting is relatively slow process. It is recommended to use Metrix++ extensions API instead.</p>
+        </section>
         <section id="extend_section">
           <div class="page-header">
             <h1>Create plugin</h1>
@@ -703,17 +960,31 @@ file: __global__: comment
     ================================================== -->
     <footer class="footer">
       <div class="container">
-        <p>Copyright <strong>&copy;</strong> 2009 - 2013, <a href="mailto:avkonst@users.sourceforge.net"><span class="normalImportance">Metrix++</span> Project</a></p>
-        <p>Code licensed under <a href="http://www.gnu.org/licenses/gpl.txt" target="_blank">GPL 3.0</a>, documentation under <a href="http://creativecommons.org/licenses/by/3.0/">CC BY 3.0</a>.</p>
-        <ul class="footer-links">
-          <li><a href="#">Report defect</a></li>
-          <li class="muted">&middot;</li>
-          <li><a href="#">Feature request</a></li>
-          <li class="muted">&middot;</li>
-          <li><a href="#">Known issues</a></li>
-          <li class="muted">&middot;</li>
-          <li><a href="#">Changelog</a></li>
-        </ul>
+      	<div class="row">
+      		<div class="span3">
+      			<p><a href="http://sourceforge.net/projects/metrixplusplus/"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=275605&amp;type=3"
+		        	alt="Get Metrix++ at SourceForge.net. Fast, secure and Free Open Source software downloads" border="0"></a></p>
+		        <p>&middot;</p>
+		        <p>&middot; &middot;<script type="text/javascript" src="http://www.ohloh.net/p/485947/widgets/project_users_logo.js"></script></p>
+		        <p><a href="http://freecode.com/projects/metrix"><img src="assets/img/fm_logo.png" width="130"></a></p>
+		        <p>&middot;</p>
+      		</div>
+      		<div class="span9">
+		        <p>Copyright <strong>&copy;</strong> 2009 - 2013, <a href="mailto:avkonst@users.sourceforge.net"><span class="normalImportance">Metrix++</span> Project</a></p>
+		        <p>Code licensed under <a href="http://www.gnu.org/licenses/gpl.txt" target="_blank">GPL 3.0</a>, documentation under <a href="http://creativecommons.org/licenses/by/3.0/">CC BY 3.0</a>.</p>
+		        <ul class="footer-links">
+		          <li><a href="https://sourceforge.net/p/metrixplusplus/tickets/new/">Ask question</a></li>
+		          <li class="muted">&middot;</li>
+		          <li><a href="https://sourceforge.net/p/metrixplusplus/tickets/new/">Report defect</a></li>
+		          <li class="muted">&middot;</li>
+		          <li><a href="https://sourceforge.net/p/metrixplusplus/tickets/new/">Feature request</a></li>
+		          <li class="muted">&middot;</li>
+		          <li><a href="https://sourceforge.net/p/metrixplusplus/tickets/search/?q=%21status%3Awont-fix+%26%26+%21status%3Aclosed">Open issues</a></li>
+		          <li class="muted">&middot;</li>
+		          <li><a href="https://sourceforge.net/p/metrixplusplus/wiki/ChangeLog/">Changelog</a></li>
+		        </ul>
+            </div>
+        </div>
       </div>
     </footer>
 

mainline/tests/system/test_boost_parts.py

@@ -91,6 +91,14 @@ class Test(tests.common.TestCase):
                                          exit_code=9)
         self.assertExec(runner.run())
 
+        runner = tests.common.ToolRunner('limit',
+                                         ['--log-level=INFO',
+                                          '--max-limit=std.code.complexity:cyclomatic:15',
+                                          '--hotspots=3'],
+                                         check_stderr=[(0, -1)],
+                                         exit_code=3)
+        self.assertExec(runner.run())
+
         runner = tests.common.ToolRunner('limit',
                                          ['--log-level=INFO',
                                           '--max-limit=std.code.complexity:cyclomatic:15',

mainline/tests/system/test_boost_parts/test_workflow_limit_default_stderr.gold.txt

@@ -1,4 +1,4 @@
 [LOG]: WARNING:	Logging enabled with INFO level
 [LOG]: INFO:	Processing: 
 [LOG]: INFO:	Applying limit: namespace 'std.code.complexity', filter '('cyclomatic', '>', 15.0)'
-[LOG]: WARNING:	Done (1 seconds). Exit code: 9
+[LOG]: WARNING:	Done (1 seconds). Exit code: 3

mainline/tests/system/test_boost_parts/test_workflow_limit_default_stdout.gold.txt

@@ -1,21 +1,3 @@
-./interprocess/detail/xsi_shared_memory_device.hpp:267: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_open_or_create_name_only' exceeds the limit.
-	Metric name    : std.code.complexity:cyclomatic
-	Region name    : priv_open_or_create_name_only
-	Metric value   : 16
-	Modified       : None
-	Change trend   : None
-	Limit          : 15.0
-	Suppressed     : False
-
-./interprocess/streams/vectorstream.hpp:284: warning: Metric 'std.code.complexity:cyclomatic' for region 'seekoff' exceeds the limit.
-	Metric name    : std.code.complexity:cyclomatic
-	Region name    : seekoff
-	Metric value   : 25
-	Modified       : None
-	Change trend   : None
-	Limit          : 15.0
-	Suppressed     : False
-
 ./interprocess/detail/managed_open_or_create_impl.hpp:302: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_open_or_create' exceeds the limit.
 	Metric name    : std.code.complexity:cyclomatic
 	Region name    : priv_open_or_create
@@ -25,37 +7,10 @@
 	Limit          : 15.0
 	Suppressed     : False
 
-./interprocess/ipc/message_queue.hpp:375: warning: Metric 'std.code.complexity:cyclomatic' for region 'insert_at' exceeds the limit.
-	Metric name    : std.code.complexity:cyclomatic
-	Region name    : insert_at
-	Metric value   : 16
-	Modified       : None
-	Change trend   : None
-	Limit          : 15.0
-	Suppressed     : False
-
-./interprocess/mapped_region.hpp:575: warning: Metric 'std.code.complexity:cyclomatic' for region 'mapped_region' exceeds the limit.
-	Metric name    : std.code.complexity:cyclomatic
-	Region name    : mapped_region
-	Metric value   : 18
-	Modified       : None
-	Change trend   : None
-	Limit          : 15.0
-	Suppressed     : False
-
-./interprocess/mem_algo/detail/mem_algo_common.hpp:452: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_allocate_many' exceeds the limit.
-	Metric name    : std.code.complexity:cyclomatic
-	Region name    : priv_allocate_many
-	Metric value   : 20
-	Modified       : None
-	Change trend   : None
-	Limit          : 15.0
-	Suppressed     : False
-
-./interprocess/mem_algo/rbtree_best_fit.hpp:787: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_expand_both_sides' exceeds the limit.
+./interprocess/streams/vectorstream.hpp:284: warning: Metric 'std.code.complexity:cyclomatic' for region 'seekoff' exceeds the limit.
 	Metric name    : std.code.complexity:cyclomatic
-	Region name    : priv_expand_both_sides
-	Metric value   : 17
+	Region name    : seekoff
+	Metric value   : 25
 	Modified       : None
 	Change trend   : None
 	Limit          : 15.0
@@ -70,12 +25,3 @@
 	Limit          : 15.0
 	Suppressed     : False
 
-./interprocess/sync/windows/named_sync.hpp:98: warning: Metric 'std.code.complexity:cyclomatic' for region 'open_or_create' exceeds the limit.
-	Metric name    : std.code.complexity:cyclomatic
-	Region name    : open_or_create
-	Metric value   : 18
-	Modified       : None
-	Change trend   : None
-	Limit          : 15.0
-	Suppressed     : False
-