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

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml	2009-09-09 04:25:19 UTC (rev 288182)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml	2009-09-09 04:26:15 UTC (rev 288183)
@@ -59,6 +59,22 @@
   </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.
+   </para>
+   <example><info><title>Setting the default report width to be 120 characters</title></info>
+    <screen>
+     <userinput>
+<![CDATA[
+$ phpcs --config-set report_width 120
+]]>
+     </userinput>
+    </screen>
+   </example>
+  </refsection>
+
+
   <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.tab-width"><info><title>Setting the Default Tab Width</title></info>
    <para>
     By default, PHP_CodeSniffer will not convert tabs to spaces in checked files. Specifying a tab width will make PHP_CodeSniffer replace tabs with spaces. You can force PHP_CodeSniffer to replace tabs with spaces by default by setting the <literal>tab_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	2009-09-09 04:25:19 UTC (rev 288182)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/reporting.xml	2009-09-09 04:26:15 UTC (rev 288183)
@@ -230,8 +230,105 @@
  </refsection>


-  <refsection xml:id="package.php.php-codesniffer.reporting.report-file"><info><title>Writing a Report to a File</title></info>
+ <refsection xml:id="package.php.php-codesniffer.reporting.svnblame-report"><info><title>Printing an SVN Blame Report</title></info>
   <para>
+   PHP_CodeSniffer can make use of the <literal>svn blame</literal> command to try and determine who committed each error and warning to an SVN respository. To print an SVN Blame report, use the <literal>--report=svnblame</literal> command line argument. The output will look like this:
+  </para>
+  <example><info><title>Sample PHP_CodeSniffer SVN Blame output</title></info>
+   <screen>
+<![CDATA[
+$ phpcs --report=svnblame /path/to/code
+
+PHP CODE SNIFFER SVN BLAME SUMMARY
+--------------------------------------------------------------------------------
+AUTHOR                                                              COUNT (%)
+--------------------------------------------------------------------------------
+jsmith                                                              51 (40.8)
+jblogs                                                              44 (30)
+pdeveloper                                                          43 (10.33)
+jscript                                                             27 (19.84)
+--------------------------------------------------------------------------------
+A TOTAL OF 165 SNIFF VIOLATION(S) WERE COMMITTED BY 4 AUTHOR(S)
+--------------------------------------------------------------------------------
+]]>
+   </screen>
+  </example>
+  <para>
+   Each author is listed with the number of violations they committed and the percentage of error lines to clean lines. The example report above shows that the developer <literal>pdeveloper</literal> has 43 violations but they only make up 10% of all code they have committed, while <literal>jblogs</literal> has 44 violations but they make up 30% of all their committed code. So these developers have about the same number of total violations, but <literal>pdeveloper</literal> seems to be doing a better job of conforming to the coding standard.
+  </para>
+  <para>
+   To show a breakdown of the types of violations each author is committing, use the <literal>-s</literal> command line argument.
+  </para>
+  <example><info><title>Sample PHP_CodeSniffer SVN Blame output with sources</title></info>
+   <screen>
+<![CDATA[
+$ phpcs -s --report=svnblame /path/to/code
+
+PHP CODE SNIFFER SVN BLAME SUMMARY
+--------------------------------------------------------------------------------
+AUTHOR   SOURCE                                                     COUNT (%)
+--------------------------------------------------------------------------------
+jsmith                                                              51 (40.8)
+         Squiz.Files.LineLength                                     47
+         PEAR.Functions.FunctionCallSignature                       4
+jblogs                                                              44 (30)
+         Squiz.Files.LineLength                                     40
+         Generic.CodeAnalysis.UnusedFunctionParameter               2
+         Squiz.CodeAnalysis.EmptyStatement                          1
+         Squiz.Formatting.MultipleStatementAlignment                1
+--------------------------------------------------------------------------------
+A TOTAL OF 95 SNIFF VIOLATION(S) WERE COMMITTED BY 2 AUTHOR(S)
+--------------------------------------------------------------------------------
+]]>
+   </screen>
+  </example>
+    <para>
+   To include authors with no violations, and perhaps shower them with praise, use the <literal>-v</literal> command line argument.
+  </para>
+  <example><info><title>Sample PHP_CodeSniffer SVN Blame verbose output</title></info>
+   <screen>
+<![CDATA[
+$ phpcs -v --report=svnblame /path/to/code
+
+PHP CODE SNIFFER SVN BLAME SUMMARY
+--------------------------------------------------------------------------------
+AUTHOR                                                              COUNT (%)
+--------------------------------------------------------------------------------
+jsmith                                                              51 (40.8)
+jblogs                                                              44 (30)
+pdeveloper                                                          43 (10.33)
+jscript                                                             27 (19.84)
+toogood                                                             0 (0)
+--------------------------------------------------------------------------------
+A TOTAL OF 165 SNIFF VIOLATION(S) WERE COMMITTED BY 5 AUTHOR(S)
+--------------------------------------------------------------------------------
+]]>
+   </screen>
+  </example>
+  <note>
+   <simpara>
+    You need to make sure the location of the <literal>svn</literal> command is in your path and that SVN is storing a username and password (if required by your repository). If the command is not in your path, the report will fail to generate. If SVN does not have a username and password stored, you'll need to enter it for each file being checked by PHP_CodeSniffer that contains violations.
+   </simpara>
+  </note>
+ </refsection>
+
+
+ <refsection xml:id="package.php.php-codesniffer.reporting.report-width"><info><title>Specifying a 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.
+  </para>
+  <example><info><title>Setting the report width to be 120 characters</title></info>
+   <screen>
+<![CDATA[
+$ phpcs --report-width=120 --report=summary /path/to/code/myfile.php
+]]>
+   </screen>
+  </example>
+ </refsection>
+
+
+ <refsection xml:id="package.php.php-codesniffer.reporting.report-file"><info><title>Writing a Report to a File</title></info>
+  <para>
    PHP_CodeSniffer always prints the specified report to the screen, but it can also be told to write a copy of the report to a file. When writing to a file, all internal parsing errors and verbose output PHP_CodeSniffer produces will not be included in the file. This feature is particularly useful when using report types such as XML and CSV that are often parsed by scripts or used with continuous integration software.
   </para>
   <para>