svn: /pear/peardoc/trunk/en/package/php/php-codesniffer/ advanced-usage.xml config-options.xml reporting.xml usage.xml

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/advanced-usage.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/advanced-usage.xml	2010-07-15 02:29:43 UTC (rev 301277)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/advanced-usage.xml	2010-07-15 03:52:31 UTC (rev 301278)
@@ -100,7 +100,7 @@

  <refsection xml:id="package.php.php-codesniffer.advanced-usage.sniffs"><info><title>Limiting Results to Specific Sniffs</title></info>
   <para>
-   By default, PHP_CodeSniffer will ceck your code using all sniffs in the specified standard. Sometimes you may want to find all occcurances of an error to eliminate it more quickly or understand the scope of the problem. PHP_CodeSniffer allows you to specify a list of sniffs to limit results to using the <literal>--sniffs</literal> command line argument. Sniffs are separated by commas.
+   By default, PHP_CodeSniffer will check your code using all sniffs in the specified standard. Sometimes you may want to find all occurrences of an error to eliminate it more quickly or understand the scope of the problem. PHP_CodeSniffer allows you to specify a list of sniffs to limit results to using the <literal>--sniffs</literal> command line argument. Sniffs are separated by commas.
   </para>
   <example><info><title>Checking files for two specific sniffs only</title></info>
    <screen>
@@ -117,6 +117,40 @@
  </refsection>


+ <refsection xml:id="package.php.php-codesniffer.advanced-usage.severity"><info><title>Filtering Errors and Warnings Based on Severity</title></info>
+  <para>
+   By default, PHP_CodeSniffer assigns a severity of <literal>5</literal> to all errors and warnings. Standards, especially custom standards, may change the severity of some messages so they are hidden by default or even so that they are raised to indicate greater importance. PHP_CodeSniffer allows you to decide what the minimum severity level must be to show a message in its report using the <literal>--severity</literal> command line argument.
+  </para>
+  <example><info><title>Hiding errors and warnings with a severity less than 3</title></info>
+   <screen>
+<![CDATA[
+$ phpcs --severity=3 /path/to/code
+]]>
+   </screen>
+  </example>
+  <para>
+   You can specify different values for errors and warnings using the <literal>--error-severity</literal> and <literal>--warning-severity</literal> command line arguments.
+  </para>
+  <example><info><title>Showing all errors but only warnings with a severity of 8 or more</title></info>
+   <screen>
+<![CDATA[
+$ phpcs --error-severity=1 --warning-severity=8 /path/to/code
+]]>
+   </screen>
+  </example>
+  <note>
+   <simpara>
+    Setting the severity of warnings to <literal>0</literal> is the same as using the <literal>-n</literal> command line argument. If you set the severity of errors to <literal>0</literal> PHP_CodeSniffer will not show any errors, which may be useful if you just want to show the warnings.
+   </simpara>
+  </note>
+  <note>
+   <simpara>
+    This feature is particularly useful during manual code reviews. During normal development or an automated build, you may want to only check code formatting issues while during a code review you may wish to show less severe errors and warnings that may need manual peer review.
+   </simpara>
+  </note>
+ </refsection>
+
+
  <refsection xml:id="package.php.php-codesniffer.advanced-usage.replace-tabs-spaces"><info><title>Replacing Tabs with Spaces</title></info>
   <para>
    Most of the sniffs written for PHP_CodeSniffer do not support the usage of tabs for indentation and alignment. You can write your own sniffs that check for tabs instead of spaces, but you can also get PHP_CodeSniffer to convert your tabs into spaces before a file is checked. This allows you to use the existing space-based sniffs on your tab-based files.
@@ -325,7 +359,7 @@
     </itemizedlist>
    </para>
    <para>
-    The level map is most commonly used to determine indentation rules (eg. a token 4 levels deep requires 16 spaces of indentation) or to determine if a particular token is within a particular scope (eg. a <literal>function</literal> keyword is within a class scope, making it a method).
+    The level map is most commonly used to determine indentation rules (e.g., a token 4 levels deep requires 16 spaces of indentation) or to determine if a particular token is within a particular scope (eg. a <literal>function</literal> keyword is within a class scope, making it a method).
    </para>
   </refsection>
  </refsection>

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml	2010-07-15 02:29:43 UTC (rev 301277)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml	2010-07-15 03:52:31 UTC (rev 301278)
@@ -59,6 +59,37 @@
   </refsection>


+  <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.severity"><info><title>Changing the Default Severity Levels</title></info>
+   <para>
+    By default, PHP_CodeSniffer will show all errors and warnings with a severity level of <literal>5</literal> or greater. You can change these settings for a single script run by using the <literal>--severity</literal>, <literal>--error-severity</literal> and <literal>--warning-severity</literal> command line arguments, but you can also change the default settings if you prefer.
+   </para>
+   <example><info><title>Changing the default severity level to show all errors and warnings</title></info>
+    <screen>
+     <userinput>
+<![CDATA[
+$ phpcs --config-set severity 1
+]]>
+     </userinput>
+    </screen>
+   </example>
+   <example><info><title>Changing the default severity levels to show all errors but only some warnings</title></info>
+    <screen>
+     <userinput>
+<![CDATA[
+$ phpcs --config-set error_severity 1
+$ phpcs --config-set warning_severity 8
+]]>
+     </userinput>
+    </screen>
+   </example>
+   <note>
+    <simpara>
+     Setting the severity of warnings to <literal>0</literal> is the same as using the <literal>-n</literal> command line argument. If you set the severity of errors to <literal>0</literal> PHP_CodeSniffer will not show any errors, which may be useful if you just want to show the warnings.
+    </simpara>
+   </note>
+  </refsection>
+
+
   <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.report-width"><info><title>Setting the Default Report Width</title></info>
    <para>
     By default, PHP_CodeSniffer will print all screen-based reports 80 characters wide. File paths will be truncated if they don't fit within this limit and error messages will be wrapped across multiple lines. You can increase the report width to show longer file paths and limit the wrapping of error messages using the <literal>-report-width</literal> command line argument, but you can also change the default report width by setting the <literal>report_width</literal> configuration option.

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/reporting.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/reporting.xml	2010-07-15 02:29:43 UTC (rev 301277)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/reporting.xml	2010-07-15 03:52:31 UTC (rev 301278)
@@ -313,8 +313,20 @@
  </refsection>


-  <refsection xml:id="package.php.php-codesniffer.reporting.interactive"><info><title>Running Interactively</title></info>
+ <refsection xml:id="package.php.php-codesniffer.reporting.gitblame-report"><info><title>Printing a Git Blame Report</title></info>
   <para>
+   Like the SVN Blame report, PHP_CodeSniffer can make use of the <literal>git blame</literal> command to try and determine who committed each error and warning to a Git respository. To print a Git Blame report, use the <literal>--report=gitblame</literal> command line argument. The output and options are the same as those described in the SVN Blame report above.
+  </para>
+  <note>
+   <simpara>
+    You need to make sure the location of the <literal>git</literal> command is in your path. If the command is not in your path, the report will fail to generate.
+   </simpara>
+  </note>
+ </refsection>
+
+
+ <refsection xml:id="package.php.php-codesniffer.reporting.interactive"><info><title>Running Interactively</title></info>
+  <para>
    Instead of producing a single report at the end of a run, PHP_CodeSniffer can run interactively and show reports for files one at a time. When using the interactive mode, PHP_CodeSniffer will show a report for the first file it finds an error or warning in. It will then pause and wait for user input. Once you have corrected the errors, you can press <literal>ENTER</literal> to have PHP_CodeSniffer recheck your file and continue if the file is now free of errors. You can also choose to skip the file and move to the next file with errors.
   </para>
   <para>

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml	2010-07-15 02:29:43 UTC (rev 301277)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml	2010-07-15 03:52:31 UTC (rev 301278)
@@ -14,10 +14,11 @@
 <![CDATA[
 Usage: phpcs [-nwlsavi] [--extensions=<extensions>] [--ignore=<patterns>]
     [--report=<report>] [--report-width=<reportWidth>] [--report-file=<reportfile>]
+    [--severity=<severity>] [--error-severity=<severity>] [--warning-severity=<severity>]
     [--config-set key value] [--config-delete key] [--config-show]
     [--standard=<standard>] [--sniffs=<sniffs>]
     [--generator=<generator>] [--tab-width=<tabWidth>] <file> ...
-        -n            Do not print warnings
+        -n            Do not print warnings (shortcut for --warning-severity=0)
         -w            Print both warnings and errors (on by default)
         -l            Local directory only, no recursion
         -s            Show sniff codes in all reports
@@ -33,12 +34,15 @@
                       to ignore directories and files
         <sniffs>      A comma separated list of sniff codes to limit the check to
                       (all sniffs must be part of the specified standard)
+        <severity>    The minimum severity that an error or warning must have
+                      for it to be displayed.
         <standard>    The name of the coding standard to use
         <tabWidth>    The number of spaces each tab represents
         <generator>   The name of a doc generator to use
                       (forces doc generation instead of checking)
         <report>      Print either the "full", "xml", "checkstyle",
-                      "csv", "emacs", "source", "summary" or "svnblame" report
+                      "csv", "emacs", "source", "summary",
+                      "svnblame" or "gitblame" report
                       (the "full" report is printed by default)
         <reportWidth> How many columns wide screen reports should be printed
         <reportfile>  Write the report to the specified file path