From da1921b4d005b2cdcf26ad49ada050123fd54b22 Mon Sep 17 00:00:00 2001
From: Roman Ivanov <ivanov-jr@mail.ru>
Date: Thu, 18 Jun 2015 00:00:56 -0700
Subject: [PATCH] NPathComplexity: extend documentation to make clear how it
 works. #1218

---
 src/xdocs/config_metrics.xml | 63 +++++++++++++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 4 deletions(-)

diff --git a/src/xdocs/config_metrics.xml b/src/xdocs/config_metrics.xml
index 0eea6b4e1..53f73a673 100644
--- a/src/xdocs/config_metrics.xml
+++ b/src/xdocs/config_metrics.xml
@@ -416,13 +416,68 @@ class CC {
           paths through a function. It takes into account the nesting of
           conditional statements and multi-part boolean expressions
           (e.g., A &amp;&amp; B, C || D, etc.).
+          <br/>
+          The NPATH metric was designed base on Cyclomatic complexity to 
+          avoid problem of Cyclomatic complexity metric like nesting level within a function.
+        </p>
+        <p>
+          Metic wsa described at <a href="http://dl.acm.org/citation.cfm?id=42379">"NPATH: a measure of execution path complexity and its applications"</a>. If you need detaled description of algorithm, please read that article,
+          it well written and have number of examples and details.
         </p>
 
+        <p>Here is some quotes:</p>
+
+        <blockquote>An NPATH threshold value of 200 has been established
+          for a function. The value 200 is based on studies done 
+          at AT&amp;T Bell Laboratories [1988 year].
+        </blockquote>
+
+        <blockquote>
+        Some of the most effective methods of reducing the NPATH value include<br/> 
+        - distributing functionality,<br/>
+        - implementing multiple if statements as a switch statement<br/>
+        - creating a separate function for logical expressions with a high count of and (&amp;&amp;) and or (||) operators.
+        </blockquote>
+
+        <blockquote>
+        Although strategies to reduce the NPATH complexity
+        of functions are important, care must be taken not to 
+        distort the logical clarity of the software by applying a 
+        strategy to reduce the complexity of functions. That is, 
+        there is a point of diminishing return beyond which a 
+        further attempt at reduction of complexity distorts the 
+        logical clarity of the system structure.
+        </blockquote>
+
+        <table>
+        <thead><tr><th>Structure</th><th> Complexity expression </th></tr></thead>
+        <tr><td>if</td><td>NP((if-range))+NP((expr))+1</td></tr>
+        <tr><td>if-else</td><td>NP((if-range))+NP((else-range))+NP((expr))</td></tr> 
+        <tr><td>while</td><td>NP((while-range))+NP((expr))+1</td></tr>
+        <tr><td>do while</td><td>NP((do-range))+NP((expr))+1</td></tr>
+        <tr><td>for</td><td>NP((for-range))+NP((exprl))+NP((expr2))+NP((expr3))+1</td></tr>
+        <tr><td>switch</td><td>NP((expr))+ S(i=1:i=n)NP((case-range(i)))+ NP((default-range))</td></tr>
+        <tr><td>?</td><td>NP((exprl))+NP((expr2))+NP((expr3))+2</td></tr>
+        <tr><td>goto label</td><td>1</td></tr>
+        <tr><td>break</td><td>1</td></tr>
+        <tr><td>Expressions</td><td>Number of &amp;&amp; and || operators in expression</td></tr>
+        <tr><td>continue</td><td>1</td></tr>
+        <tr><td>return</td><td>1</td></tr>
+        <tr><td>sequential</td><td>1</td></tr>
+        <tr><td>Function call</td><td>1</td></tr>
+        <tr><td>C function</td><td>P(i=1:i=N) NP(Statement(i))</td></tr>
+        </table>
+
+
         <p>
-          Rationale: Nejmeh says that his group had an informal NPATH
+          <b>Rationale:</b> Nejmeh says that his group had an informal NPATH
           limit of 200 on individual routines; functions that exceeded
           this value were candidates for further decomposition - or at
-          least a closer look.
+          least a closer look. 
+          <b>Please do not be fanatic with limit 200</b>
+          - choose number that suites your project style. Limit 200 is 
+          empirical number base on some sources of at AT&amp;T Bell Laboratories 
+          of 1988 year.
         </p>
       </subsection>
 
@@ -452,11 +507,11 @@ class CC {
         </source>
 
         <p>
-          To configure the check with a threshold of 20:
+          To configure the check with a threshold of 1000:
         </p>
         <source>
 &lt;module name=&quot;NPathComplexity&quot;&gt;
-    &lt;property name=&quot;max&quot; value=&quot;20&quot;/&gt;
+    &lt;property name=&quot;max&quot; value=&quot;1000&quot;/&gt;
 &lt;/module&gt;
         </source>
       </subsection>