svn: /pear/peardoc/trunk/en/package/php/ php-codesniffer/annotated-ruleset.xml php-codesniffer/coding-standard-class.xml php-codesniffer/coding-standard-tutorial.xml php-codesniffer.xml

Added: pear/peardoc/trunk/en/package/php/php-codesniffer/annotated-ruleset.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/annotated-ruleset.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/annotated-ruleset.xml	2010-08-31 01:50:17 UTC (rev 302906)
@@ -0,0 +1,206 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.php.php-codesniffer.annotated-ruleset">
+ <refnamediv>
+  <refname>Annotated ruleset.xml</refname>
+  <refpurpose>A sample ruleset.xml file that describes all features of the format</refpurpose>
+ </refnamediv>
+
+ <refsection><info><title>Introduction</title></info>
+  <para>
+   PHP_CodeSniffer allows developers to design their own coding standards by creating a simple ruleset XML file that both pulls in sniffs from existing standards and customises them for the developer's needs. This XML file can be named anything you like, as long as it has an <literal>xml</literal> extension and complies to the ruleset.xml format. The file can be stored anywhere, making it perfect for placing under version control with a project's source code and unit tests.
+  </para>
+  <para>
+   Once created, a ruleset file can be used with the <literal>--standard</literal> command line argument. In the following example, PHP_CodeSniffer will use the coding standard defined in a custom ruleset file called custom_ruleset.xml:
+  </para>
+  <example><info><title>Using a custom ruleset file</title></info>
+   <screen>
+<![CDATA[
+$ phpcs --standard=/path/to/custom_ruleset.xml test.php
+]]>
+   </screen>
+  </example>
+ </refsection>
+
+ <refsection><info><title>The Annotated Sample File</title></info>
+  <para>
+   The following sample file documents the ruleset.xml format and shows you the complete range of features that the format supports. The file is designed for documentation purposes only and is not a working coding standard.
+  </para>
+  <para>
+   <programlisting role="xml">
+<![CDATA[
+<?xml version="1.0"?>
+<ruleset name="Custom Standard">
+
+ <!--
+    The name attribute of the ruleset tag is displayed
+    when running PHP_CodeSniffer with the -v command line
+    argument. The description tag below is not displayed anywhere
+    except in this file, so it can contain information for
+    developers who may change this file in the future.
+ -->
+ <description>A custom coding standard</description>
+
+ <!--
+    You can hard-code ignore patterns directly into your
+    custom standard so you don't have to specify the
+    patterns on the command line.
+
+    The following two tags are equivalent to the command line
+    argument: --ignore=*/tests/*,*/data/*
+ -->
+ <exclude-pattern>*/tests/*</exclude-pattern>
+ <exclude-pattern>*/data/*</exclude-pattern>
+
+ <!--
+    Include all sniffs in the PEAR standard. Note that the
+    path to the standard does not have to be specified as the
+    PEAR standard exists inside the PHP_CodeSniffer install
+    directory.
+ -->
+ <rule ref="PEAR"/>
+
+ <!--
+    Include all sniffs in an external standard directory. Note
+    that we have to specify the full path to the standard's
+    directory because it does not exist inside the PHP_CodeSniffer
+    install directory.
+ -->
+ <rule ref="/home/username/standards/mystandard"/>
+
+ <!--
+    Include everything in another ruleset.xml file. This is
+    really handy if you want to customise another developer's
+    custom standard. They just need to distribute their single
+    ruleset file to allow this.
+ -->
+ <rule ref="/home/username/standards/custom.xml"/>
+
+ <!--
+    Include all sniffs in the Squiz standard except one. Note that
+    the name of the sniff being excluded is the code that the sniff
+    is given by PHP_CodeSniffer and is based on the file name and
+    path of the sniff class. You can display these codes using the
+    -s command line argument when checking a file.
+ -->
+ <rule ref="Squiz">
+  <exclude name="Squiz.PHP.CommentedOutCode"/>
+ </rule>
+
+ <!--
+    Include some specific sniffs from the Generic standard.
+    Note again that the name of the sniff is the code that
+    PHP_CodeSniffer gives it.
+ -->
+ <rule ref="Generic.CodeAnalysis.UnusedFunctionParameter"/>
+ <rule ref="Generic.Commenting.Todo"/>
+ <rule ref="Generic.ControlStructures.InlineControlStructure"/>
+
+ <!--
+    Here we are including a specific sniff but also changing
+    the error message of a specific message inside the sniff.
+    Note that the specific code for the message, which is
+    CommentFound in this case, is defined by the sniff developer.
+    You can display these codes by using the -s command line
+    argument when checking a file.
+
+    Also note that this message has a variable inside it,
+    which is why it is important that sniffs use a printf style
+    format for their error messages.
+
+    We also drop the severity of this message from the
+    default value (5) so that it is hidden by default. It can be
+    displayed by setting the minimum severity on the PHP_CodeSniffer
+    command line. This is great if you want to use some messages
+    only in code reviews and not have them block code commits.
+ -->
+ <rule ref="Generic.Commenting.Todo.CommentFound">
+  <message>Please review this TODO comment: %s</message>
+  <severity>3</severity>
+ </rule>
+
+ <!--
+    Here we change two messages from the same sniff. Note how the
+    codes are slightly different because the sniff developer has
+    defined both a MaxExceeded message and a TooLong message. In the
+    case of this sniff, one is used for warnings and one is used
+    for errors.
+ -->
+ <rule ref="Generic.Files.LineLength.MaxExceeded">
+  <message>Line contains %s chars, which is longer than the max limit of %s</message>
+ </rule>
+ <rule ref="Generic.Files.LineLength.TooLong">
+  <message>Line longer than %s characters; contains %s characters</message>
+ </rule>
+
+ <!--
+    Some sniffs have public member vars that allow you to
+    customise specific elements of the sniff. In the case of
+    the Generic LineLength sniff, you can customise the limit
+    at which the sniff will throw warnings and the limit at
+    which it will throw errors.
+
+    The rule below includes the LineLength sniff but changes the
+    settings so the sniff will show warnings for any line longer
+    than 90 chars and errors for any line longer than 100 chars.
+ -->
+ <rule ref="Generic.Files.LineLength">
+  <properties>
+   <property name="lineLimit" value="90"/>
+   <property name="absoluteLineLimit" value="100"/>
+  </properties>
+ </rule>
+
+ <!--
+    Another useful example of changing sniff settings is
+    to specify the end of line character that your standard
+    should check for.
+ -->
+ <rule ref="Generic.Files.LineEndings">
+  <properties>
+   <property name="eolChar" value="\r\n"/>
+  </properties>
+ </rule>
+
+ <!--
+    Boolean values should be specified by using the strings
+    "true" and "false" rather than the integers 0 and 1.
+ -->
+ <rule ref="Generic.Formatting.MultipleStatementAlignment">
+  <properties>
+   <property name="maxPadding" value="8"/>
+   <property name="ignoreMultiLine" value="true"/>
+   <property name="error" value="true"/>
+  </properties>
+ </rule>
+
+ <!--
+    If you want to completely disable an error message in a sniff
+    but you don't want to exclude the whole sniff, you can
+    change the severity of the message to 0. In this case, we
+    want the Squiz DoubleQuoteUsage sniff to be included in our
+    standard, but we don't want the ContainsVar error message to
+    ever be displayed.
+ -->
+ <rule ref="Squiz.Strings.DoubleQuoteUsage.ContainsVar">
+  <severity>0</severity>
+ </rule>
+
+ <!--
+    There is a special internal error message produce by PHP_CodeSniffer
+    when it is unable to detect code in a file, possible due to
+    the use of short open tags even though php.ini disables them.
+    You can disable this message in the same way as sniff messages.
+
+    Again, the code here will be displayed in the PHP_CodeSniffer
+    output when using the -s command line argument while checking a file.
+ -->
+ <rule ref="Internal.NoCodeFound">
+  <severity>0</severity>
+ </rule>
+
+</ruleset>
+]]>
+   </programlisting>
+  </para>
+ </refsection>
+</refentry>

Deleted: pear/peardoc/trunk/en/package/php/php-codesniffer/coding-standard-class.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/coding-standard-class.xml	2010-08-31 01:44:15 UTC (rev 302905)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/coding-standard-class.xml	2010-08-31 01:50:17 UTC (rev 302906)
@@ -1,103 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.php.php-codesniffer.coding-standard-class">
- <refnamediv>
-  <refname>Coding Standard Class Methods</refname>
-  <refpurpose>Information about overriding coding standard class methods</refpurpose>
- </refnamediv>
-
- <refsection><info><title>Introduction</title></info>
-
-  <para>
-   Every coding standard contains a class file. This file allows PHP_CodeSniffer to ask a coding standard for information about itself, and also identify a directory as one that contains code sniffs. This guide describes each of the coding standard class methods that can be overridden to provide additional information about your coding standard to PHP_CodeSniffer.
-  </para>
- </refsection>
-
- <refsection><info><title>The getIncludedSniffs() Method</title></info>
-
-  <para>
-   This method allows you to tell PHP_CodeSniffer that, besides the code sniffs you have defined in your <filename>Sniffs</filename> directory, you want to include code sniffs from other coding standards. You can include single code sniffs, whole directories of code sniffs, or an entire coding standard.
-  </para>
-  <para>
-   The example below includes the <literal>MultipleStatementAlignment</literal> sniff from the <literal>Generic</literal> coding standard, all code sniffs in the <literal>Functions</literal> category of the <literal>Generic</literal> coding standard, and all code sniffs defined in the <literal>PEAR</literal> coding standard.
-  </para>
-  <para>
-   <programlisting role="php">
-<![CDATA[
-<?php
-/**
- * Return a list of external sniffs to include with this standard.
- *
- * The MyStandard coding standard uses some generic sniffs, and
- * the entire PEAR coding standard.
- *
- * @return array
- */
-public function getIncludedSniffs()
-{
-    return array(
-            'PEAR',
-            'Generic/Sniffs/Formatting/MultipleStatementAlignmentSniff.php',
-            'Generic/Sniffs/Functions',
-           );
-
-}//end getIncludedSniffs()
-?>
-]]>
-   </programlisting>
-  </para>
-  <note>
-   <simpara>
-    When including an entire coding standard, you will also include any code sniffs that the standard includes from other coding standards. For example, the <literal>PEAR</literal> coding standard includes some code sniffs from the <literal>Generic</literal> coding standard, so including the entire <literal>PEAR</literal> coding standard will also include those code sniffs. This is a quick and easy way to create your own coding standard based on an existing one.
-   </simpara>
-  </note>
- </refsection>
-
- <refsection><info><title>The getExcludedSniffs() Method</title></info>
-
-  <para>
-   This method allows you to tell PHP_CodeSniffer to exclude code sniffs from your own standard or any other standard you are including using the <function>getIncludedSniffs</function> method. You can exclude single code sniffs, whole directories of code sniffs, or an entire coding standard.
-  </para>
-  <para>
-   The example below includes the whole <literal>PEAR</literal> coding standard, except for the <literal>ControlSignature</literal> sniff.
-  </para>
-  <para>
-   <programlisting role="php">
-<![CDATA[
-<?php
-/**
- * Return a list of external sniffs to include with this standard.
- *
- * The MyStandard coding standard uses all PEAR sniffs except one.
- *
- * @return array
- */
-public function getIncludedSniffs()
-{
-    return array(
-            'PEAR',
-           );
-
-}//end getIncludedSniffs()
-
-
-/**
- * Return a list of external sniffs to exclude from this standard.
- *
- * The MyStandard coding standard uses all PEAR sniffs except one.
- *
- * @return array
- */
-public function getExcludedSniffs()
-{
-    return array(
-            'PEAR/Sniffs/ControlStructures/ControlSignatureSniff.php',
-           );
-
-}//end getExcludedSniffs()
-?>
-]]>
-   </programlisting>
-  </para>
- </refsection>
-
-</refentry>

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/coding-standard-tutorial.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/coding-standard-tutorial.xml	2010-08-31 01:44:15 UTC (rev 302905)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/coding-standard-tutorial.xml	2010-08-31 01:50:17 UTC (rev 302906)
@@ -6,16 +6,14 @@
  </refnamediv>

  <refsection><info><title>Introduction</title></info>
-
   <para>
    In this tutorial, we will create a new coding standard with a single sniff. Our sniff will prohibit the use of Perl style hash comments.
   </para>
  </refsection>

  <refsection><info><title>Creating the Coding Standard Directory</title></info>
-
   <para>
-   All sniffs in PHP_CodeSniffer must belong to a coding standard. A coding standard is a directory with a specific sub-directory structure and a single class, so we can create one very easily. Let's call our coding standard <emphasis>MyStandard</emphasis>. Run the following commands to create the coding standard directory structure:
+   All sniffs in PHP_CodeSniffer must belong to a coding standard. A coding standard is a directory with a specific sub-directory structure and a ruleset.xml file, so we can create one very easily. Let's call our coding standard <emphasis>MyStandard</emphasis>. Run the following commands to create the coding standard directory structure:
   </para>
   <para>
    <screen>
@@ -47,69 +45,39 @@
    The <filename>MyStandard</filename> directory represents our coding standard. The <filename>Sniffs</filename> sub-directory is used to store all the sniff files for this coding standard.
   </para>
   <para>
-   Now that our directory structure is created, we need to add our class file. This file will allow PHP_CodeSniffer to ask our coding standard for information about itself, and also identify this directory as one that contains code sniffs.
+   Now that our directory structure is created, we need to add our ruleset.xml file. This file will allow PHP_CodeSniffer to ask our coding standard for information about itself, and also identify this directory as one that contains code sniffs.
   </para>
   <para>
    <screen>
     <userinput>
 <![CDATA[
 $ cd MyStandard
-$ touch MyStandardCodingStandard.php
+$ touch ruleset.xml
 ]]>
     </userinput>
    </screen>
   </para>
   <para>
-   The content of the <filename>MyStandardCodingStandard.php</filename> file should be the following:
+   The content of the <filename>ruleset.xml</filename> file should be the following:
   </para>
   <para>
    <programlisting role="php">
 <![CDATA[
-<?php
-/**
- * MyStandard Coding Standard.
- *
- * PHP version 5
- *
- * @category  PHP
- * @package   PHP_CodeSniffer
- * @author    Your Name <[email protected]>
- * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
- * @version   SVN: $Id: coding-standard-tutorial.xml,v 1.9 2008-10-09 15:16:47 cweiske Exp $
- * @link      http://pear.php.net/package/PHP_CodeSniffer
- */
-
-if (class_exists('PHP_CodeSniffer_Standards_CodingStandard', true) === false) {
-    throw new PHP_CodeSniffer_Exception('Class PHP_CodeSniffer_Standards_CodingStandard not found');
-}
-
-/**
- * MyStandard Coding Standard.
- *
- * @category  PHP
- * @package   PHP_CodeSniffer
- * @author    Your Name <[email protected]>
- * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
- * @version   Release: @package_version@
- * @link      http://pear.php.net/package/PHP_CodeSniffer
- */
-class PHP_CodeSniffer_Standards_MyStandard_MyStandardCodingStandard extends PHP_CodeSniffer_Standards_CodingStandard
-{
-
-}//end class
-?>
+<?xml version="1.0"?>
+<ruleset name="MyStandard">
+ <description>A custom coding standard.</description>
+</ruleset>
 ]]>
    </programlisting>
   </para>
   <note>
    <simpara>
-    The coding standard class can be left empty, as it is in this example coding standard. For information about the methods that can be overridden, see the <link linkend="package.php.php-codesniffer.coding-standard-class">coding standard class documentation</link>.
+    The ruleset.xml can be left quite small, as it is in this example coding standard. For information about the other features that the ruleset.xml provides, see the <link linkend="package.php.php-codesniffer.annotated-ruleset">annotated ruleset.xml</link>.
    </simpara>
   </note>
  </refsection>

  <refsection><info><title>Creating the Sniff</title></info>
-
   <para>
    A sniff requires a single PHP file. It's name should clearly describe the standard that we are enforcing and must end with <literal>Sniff.php</literal>. For our sniff, we will name the PHP file <filename>DisallowHashCommentsSniff.php</filename> and place it into a <filename>Commenting</filename> sub-directory to categorise this sniff as relating to commenting. Run the following commands to create the category and the sniff:
   </para>
@@ -134,7 +102,6 @@
   </para>

   <refsection><info><title>The <function>register</function> and <function>process</function> Methods</title></info>
-
    <para>
     The <function>register</function> method allows a sniff to subscribe to one or more token types that it wants to process. Once PHP_CodeSniffer encounters one of those tokens, it calls the <function>process</function> method with the <literal>PHP_CodeSniffer_File</literal> object (a representation of the current file being checked) and the position in the stack where the token was found.
    </para>
@@ -144,9 +111,8 @@
   </refsection>

   <refsection><info><title>The Token Stack</title></info>
-
    <para>
-    A sniff can gather more information about a token by acquiring the token stack with a call to the <function>getTokens</function> method on the <literal>PHP_CodeSniffer_File</literal> object. This method returns an array, and is indexed by the position where the token occurs in the token stack. Each element in the array represents a token. All tokens have a <literal>code</literal>, <literal>type</literal> and a <literal>content</literal> index in their array. The <literal>code</literal> value is a unique integer for the type of token. The <literal>type</literal> value is a string representation of the token (e.g., 'T_COMMENT' for comment tokens). The <literal>type</literal> has a corresponding globally defined integer with the same name. Finally, the <literal>content</literal> value contains the content of the token as it appears in the code.
+    A sniff can gather more information about a token by acquiring the token stack with a call to the <function>getTokens</function> method on the <literal>PHP_CodeSniffer_File</literal> object. This method returns an array and is indexed by the position where the token occurs in the token stack. Each element in the array represents a token. All tokens have a <literal>code</literal>, <literal>type</literal> and a <literal>content</literal> index in their array. The <literal>code</literal> value is a unique integer for the type of token. The <literal>type</literal> value is a string representation of the token (e.g., 'T_COMMENT' for comment tokens). The <literal>type</literal> has a corresponding globally defined integer with the same name. Finally, the <literal>content</literal> value contains the content of the token as it appears in the code.
    </para>
    <note>
     <simpara>
@@ -156,15 +122,13 @@
   </refsection>

   <refsection><info><title>Reporting Errors</title></info>
-
    <para>
-    Once an error is detected, a sniff should indicate that an error has occurred by calling the <function>addError</function> method on the <literal>PHP_CodeSniffer_File</literal> object, passing in an appropriate error message as the first argument and the position in the stack where the error was detected as the second. Alternatively, if the violation is considered not as critical as an error, the <function>addWarning</function> method can be used.
+    Once an error is detected, a sniff should indicate that an error has occurred by calling the <function>addError</function> method on the <literal>PHP_CodeSniffer_File</literal> object, passing in an appropriate error message as the first argument, the position in the stack where the error was detected as the second, a code to uniquely identify the error within this sniff and an array of data used inside the error message. Alternatively, if the violation is considered not as critical as an error, the <function>addWarning</function> method can be used.
    </para>
   </refsection>
  </refsection>

  <refsection><info><title>DisallowHashCommentsSniff.php</title></info>
-
   <para>
    We now have to write the content of our sniff. The content of the <filename>DisallowHashCommentsSniff.php</filename> file should be the following:
   </para>
@@ -231,8 +195,9 @@
     {
         $tokens = $phpcsFile->getTokens();
         if ($tokens[$stackPtr]['content']{0} === '#') {
-            $error = 'Hash comments are prohibited';
-            $phpcsFile->addError($error, $stackPtr);
+            $error = 'Hash comments are prohibited; found %s';
+            $data  = array(trim($tokens[$stackPtr]['content']));
+            $phpcsFile->addError($error, $stackPtr, 'Found', $data);
         }

     }//end process()
@@ -246,7 +211,7 @@
   </para>
   <note>
    <simpara>
-    By default, PHP_CodeSniffer assumes all sniffs are designed to check PHP code only. You can specify a list of tokenizers that your sniff supports, allowing it to be used on PHP code, JavaScript code, or both. You do this by setting the <literal>$supportedTokenizers</literal> member variable in your sniff. Adding the following code to your sniff will tell PHP_CodeSniffer that it can be used to check both PHP and JavaScript code:
+    By default, PHP_CodeSniffer assumes all sniffs are designed to check PHP code only. You can specify a list of tokenizers that your sniff supports, allowing it to be used wth PHP, JavaScript or XML files, or any combination of the three. You do this by setting the <literal>$supportedTokenizers</literal> member variable in your sniff. Adding the following code to your sniff will tell PHP_CodeSniffer that it can be used to check both PHP and JavaScript code:
    </simpara>
    <para>
     <programlisting role="php">
@@ -268,7 +233,6 @@


  <refsection><info><title>Results</title></info>
-
   <para>
    Now that we have defined a coding standard, let's validate a file that contains hash comments.
   </para>
@@ -302,15 +266,15 @@
    <para>
     <screen>
 <![CDATA[
-$ phpcs --standard=/path/to/MyStandard Test.php
+$ phpcs --standard=/path/to/MyStandard test.php

-FILE: Test.php
+FILE: test.php
 --------------------------------------------------------------------------------
-FOUND 3 ERROR(S) AND 1 WARNING(S) AFFECTING 3 LINE(S)
+FOUND 3 ERROR(S) AFFECTING 3 LINE(S)
 --------------------------------------------------------------------------------
- 3 | ERROR | Hash comments are prohibited
- 7 | ERROR | Hash comments are prohibited
- 9 | ERROR | Hash comments are prohibited
+ 3 | ERROR | Hash comments are prohibited; found # Check for valid contents.
+ 7 | ERROR | Hash comments are prohibited; found # Value needs to be an array.
+ 9 | ERROR | Hash comments are prohibited; found # Error.
 --------------------------------------------------------------------------------
 ]]>
    </screen>

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer.xml	2010-08-31 01:44:15 UTC (rev 302905)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer.xml	2010-08-31 01:50:17 UTC (rev 302906)
@@ -17,7 +17,7 @@
  &package.php.php-codesniffer.reporting;
  &package.php.php-codesniffer.config-options;
  &package.php.php-codesniffer.coding-standard-tutorial;
- &package.php.php-codesniffer.coding-standard-class;
+ &package.php.php-codesniffer.annotated-ruleset;
  &package.php.php-codesniffer.svn-pre-commit;
  &package.php.php-codesniffer.faq;
  </chapter>