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

squiz                                    Tue, 21 Dec 2010 23:29:17 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=306567

Log:
Docs for the new progress output

Changed paths:
    U   pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml
    U   pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml	2010-12-21 23:28:46 UTC (rev 306566)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml	2010-12-21 23:29:17 UTC (rev 306567)
@@ -59,6 +59,22 @@
   </refsection>


+  <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.show-progress"><info><title>Showing Progress by Default</title></info>
+   <para>
+    By default, PHP_CodeSniffer will run quietly and only print the report of errors and warnings at the end. If you want to know what is happening you can turn on progress output, but you can also enable this by default if you prefer. To show progress by default, set the <literal>show_progress</literal> configuration option to <literal>1</literal>.
+   </para>
+   <example><info><title>Showing progress by default</title></info>
+    <screen>
+     <userinput>
+<![CDATA[
+$ phpcs --config-set show_progress 1
+]]>
+     </userinput>
+    </screen>
+   </example>
+  </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.

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml	2010-12-21 23:28:46 UTC (rev 306566)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml	2010-12-21 23:29:17 UTC (rev 306567)
@@ -12,7 +12,7 @@
   <para>
    <screen>
 <![CDATA[
-Usage: phpcs [-nwlsavi] [-d key[=value]] [--extensions=<extensions>] [--ignore=<patterns>]
+Usage: phpcs [-nwlsapvi] [-d key[=value]] [--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]
@@ -23,6 +23,7 @@
         -l            Local directory only, no recursion
         -s            Show sniff codes in all reports
         -a            Run interactively
+        -p            Show progress of the run
         -v[v][v]      Print verbose output
         -i            Show a list of installed coding standards
         -d            Set the [key] php.ini value to [value] or [true] if value is omitted
@@ -178,11 +179,47 @@
  </refsection>


- <refsection xml:id="package.php.php-codesniffer.usage.verbose-output"><info><title>Printing Verbose Output</title></info>
+ <refsection xml:id="package.php.php-codesniffer.usage.verbose-output"><info><title>Printing Progress Information</title></info>
   <para>
-   By default, PHP_CodeSniffer will run quietly, only printing the report of errors and warnings at the end. If you are checking a large number of files, you may have to wait a while to see the report. If you want to know what is happening, you can turn on verbose output.
+   By default, PHP_CodeSniffer will run quietly, only printing the report of errors and warnings at the end. If you are checking a large number of files, you may have to wait a while to see the report. If you want to know what is happening, you can turn on progress or verbose output.
   </para>
   <para>
+   With progress output enabled, PHP_CodeSniffer will print a single-character status for each file being checked. The possible status characters are:
+  </para>
+  <para>
+   <simplelist>
+    <member><literal>.</literal> : The file contained no errors or warnings</member>
+    <member><literal>E</literal> : The file contained 1 or more errors</member>
+    <member><literal>W</literal> : The file contained 1 or more warnings, but no errors</member>
+    <member><literal>S</literal> : The file contained a <link linkend="package.php.php-codesniffer.advanced-usage.ignore-files-folders">@codingStandardsIgnoreFile</link> comment and was skipped</member>
+   </simplelist>
+  </para>
+  <para>
+   Progress output will look like this:
+  </para>
+  <example><info><title>Sample PHP_CodeSniffer progress output</title></info>
+   <screen>
+<![CDATA[
+$ phpcs /path/to/code/CodeSniffer -p
+......................S.....................................  60 / 572
+..........EEEE.E.E.E.E.E.E.E.E..W..EEE.E.E.E.EE.E.E.E.E.E.E. 120 / 572
+E.E.E.E.E.WWWW.E.W..EEE.E.................E.E.E.E...E....... 180 / 572
+E.E.E.E.....................E.E.E.E.E.E.E.E.E.E.W.E.E.E.E.E. 240 / 572
+E.W......................................................... 300 / 572
+..........................................E.E.E.E...E.E.E.E. 360 / 572
+E.E.E.E.E.E..E.E.E..E..E..E.E.WW.E.E.EE.E.E................. 420 / 572
+...................E.E.EE.E.E.E.S.E.EEEE.E...E...EE.E.E..EEE 480 / 572
+.E.EE.E.E..E.E.E.E.E.E.E.E.E.E.E.E.E.E.E.E.E..E..E..E.E.E..E 540 / 572
+.E.E....E.E.E...E.....E.E.ES....
+]]>
+   </screen>
+  </example>
+  <note>
+   <simpara>
+    You can configure PHP_CodeSniffer to show progress information by default using <link linkend="package.php.php-codesniffer.config-options.php-codesniffer.show-progress">the configuration option</link>.
+   </simpara>
+  </note>
+  <para>
    With verbose output enabled, PHP_CodeSniffer will print the file that it is checking, show you how many tokens and lines the file contains, and let you know how long it took to process. The output will look like this:
   </para>
   <example><info><title>Sample PHP_CodeSniffer verbose output</title></info>
@@ -190,6 +227,7 @@
 <![CDATA[
 $ phpcs /path/to/code/CodeSniffer -v
 Registering sniffs in PEAR standard... DONE (24 sniffs registered)
+Creating file list... DONE (572 files in queue)
 Processing AbstractDocElement.php [1093 tokens in 303 lines]... DONE in < 1 second (0 errors, 1 warnings)
 Processing AbstractParser.php [2360 tokens in 558 lines]... DONE in 2 seconds (0 errors, 1 warnings)
 Processing ClassCommentParser.php [923 tokens in 296 lines]... DONE in < 1 second (2 errors, 0 warnings)