doc: expanded documentation on severities

src/xdocs/property_types.xml

@@ -831,16 +831,88 @@
 
     <section name="SeverityLevel">
       <p>
-        This type represents the severity level of a check violation. The
-        valid options are:
+        This type represents the severity level of a module violation.
+        The following table describes the valid options:
       </p>
 
-      <ul>
-        <li><code>ignore</code></li>
-        <li><code>info</code></li>
-        <li><code>warning</code></li>
-        <li><code>error</code></li>
-      </ul>
+      <div class="wrapper">
+        <table>
+          <tr>
+            <td>Option</td>
+            <td>Definition</td>
+            <td><a href="cmdline.html">CLI</a></td>
+            <td><a href="anttask.html">Ant task</a></td>
+          </tr>
+
+          <tr>
+            <td><code>ignore</code></td>
+            <td>
+              If a violation occurs, modules with this severity are ignored as if they never
+              occurred.
+              This severity can be used to disable a module in the configuration.
+            </td>
+            <td>
+              Such violation not printed in output, however,
+              depending on the setting of
+              <a href="cmdline.html#Command_line_usage"><code>executeIgnoredModules</code></a>
+              when executed, the module may still run and if an exception occurs, the exception
+              will turn into an error and act as one.
+            </td>
+            <td>
+              Such violation not printed in output, however,
+              depending on the setting of
+              <a href="anttask.html#Parameters"><code>executeIgnoredModules</code></a>
+              when executed, the module may still run and if an exception occurs, the exception
+              will turn into an error and act as one.
+            </td>
+          </tr>
+
+          <tr>
+            <td><code>info</code></td>
+            <td>
+              If a violation occurs, modules with this severity are displayed as informational.
+            </td>
+            <td>
+              Displays the violation, but not fail the execution.
+            </td>
+            <td>
+              Displays the violation, but not fail the execution.
+            </td>
+          </tr>
+
+          <tr>
+            <td><code>warning</code></td>
+            <td>
+              This severity behaves exactly the same as <code>info</code> in Checkstyle.
+              It can be used to let user bring more attention to reviewers of such violations.
+            </td>
+            <td>
+              Displays the violation, but not fail the execution.
+            </td>
+            <td>
+              Displays the violation, might fail the execution.<br/>
+              <a href="anttask.html#Parameters"><code>maxWarnings</code></a> can be used to pass
+              the execution until a certain number of warnings are found.
+            </td>
+          </tr>
+
+          <tr>
+            <td><code>error</code></td>
+            <td>
+              If a violation occurs, modules with this severity are displayed as error and should
+              be considered as a failure.
+            </td>
+            <td>
+              Displays the violation, fail the execution.
+            </td>
+            <td>
+              Displays the violation, might fail the execution.<br/>
+              <a href="anttask.html#Parameters"><code>maxErrors</code></a> can be used to pass
+              the execution until a certain number of error are found.
+            </td>
+          </tr>
+        </table>
+      </div>
     </section>
 
     <section name="String">