Document all AttrDefs, also remove duplicant NumberSpan in favor of Integer.

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@308 48356398-32a2-884e-a903-53898d9a118a

library/HTMLPurifier/AttrDef/CSS.php

@@ -3,6 +3,12 @@
 require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/CSSDefinition.php';
 
+/**
+ * Validates the HTML attribute style, otherwise known as CSS.
+ * @note We don't implement the whole CSS specification, so it might be
+ *       difficult to reuse this component in the context of validating
+ *       actual stylesheet declarations.
+ */
 class HTMLPurifier_AttrDef_CSS extends HTMLPurifier_AttrDef
 {
     

library/HTMLPurifier/AttrDef/CSSLength.php

@@ -3,13 +3,29 @@
 require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/AttrDef/Number.php';
 
+/**
+ * Represents a Length as defined by CSS.
+ * @warning Be sure not to confuse this with HTMLPurifier_AttrDef_Length!
+ */
 class HTMLPurifier_AttrDef_CSSLength extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * Valid unit lookup table.
+     * @warning The code assumes all units are two characters long.  Be careful
+     *          if we have to change this behavior!
+     */
     var $units = array('em' => true, 'ex' => true, 'px' => true, 'in' => true,
          'cm' => true, 'mm' => true, 'pt' => true, 'pc' => true);
+    /**
+     * Instance of HTMLPurifier_AttrDef_Number to defer number validation to
+     */
     var $number_def;
     
+    /**
+     * @param $non_negative Bool indication whether or not negative values are
+     *                      allowed.
+     */
     function HTMLPurifier_AttrDef_CSSLength($non_negative = false) {
         $this->number_def = new HTMLPurifier_AttrDef_Number($non_negative);
     }

library/HTMLPurifier/AttrDef/Class.php

@@ -3,6 +3,9 @@
 require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/Config.php';
 
+/**
+ * Validates the contents of the global HTML attribute class.
+ */
 class HTMLPurifier_AttrDef_Class extends HTMLPurifier_AttrDef
 {
     

library/HTMLPurifier/AttrDef/Color.php

@@ -2,6 +2,9 @@
 
 require_once 'HTMLPurifier/AttrDef.php';
 
+/**
+ * Validates Color as defined by CSS.
+ */
 class HTMLPurifier_AttrDef_Color
 {
     

library/HTMLPurifier/AttrDef/Composite.php

@@ -1,10 +1,26 @@
 <?php
 
+/**
+ * Allows multiple validators to attempt to validate attribute.
+ * 
+ * Composite is just what it sounds like: a composite of many validators.
+ * This means that multiple HTMLPurifier_AttrDef objects will have a whack
+ * at the string.  If one of them passes, that's what is returned.  This is
+ * especially useful for CSS values, which often are a choice between
+ * an enumerated set of predefined values or a flexible data type.
+ */
 class HTMLPurifier_AttrDef_Composite extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * List of HTMLPurifier_AttrDef objects that may process strings
+     * @protected
+     */
     var $defs;
     
+    /**
+     * @param $defs List of HTMLPurifier_AttrDef objects
+     */
     function HTMLPurifier_AttrDef_Composite($defs) {
         $this->defs = $defs;
     }

library/HTMLPurifier/AttrDef/Enum.php

@@ -3,12 +3,27 @@
 require_once 'HTMLPurifier/AttrDef.php';
 
 // Enum = Enumerated
+/**
+ * Validates a keyword against a list of valid values.
+ */
 class HTMLPurifier_AttrDef_Enum extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * Lookup table of valid values.
+     */
     var $valid_values   = array();
+    
+    /**
+     * Bool indicating whether or not enumeration is case sensitive.
+     * @note In general this is always case insensitive.
+     */
     var $case_sensitive = false; // values according to W3C spec
     
+    /**
+     * @param $valid_values List of valid values
+     * @param $case_sensitive Bool indicating whether or not case sensitive
+     */
     function HTMLPurifier_AttrDef_Enum(
         $valid_values = array(), $case_sensitive = false) {
         

library/HTMLPurifier/AttrDef/FontFamily.php

@@ -4,9 +4,16 @@ require_once 'HTMLPurifier/AttrDef.php';
 
 // whitelisting allowed fonts would be nice
 
+/**
+ * Validates a font family list according to CSS spec
+ */
 class HTMLPurifier_AttrDef_FontFamily extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * Generic font family keywords.
+     * @protected
+     */
     var $generic_names = array(
         'serif' => true,
         'sans-serif' => true,

library/HTMLPurifier/AttrDef/Host.php

@@ -4,9 +4,15 @@ require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/AttrDef/IPv4.php';
 require_once 'HTMLPurifier/AttrDef/IPv6.php';
 
+/**
+ * Validates a host according to the IPv4, IPv6 and DNS specifications.
+ */
 class HTMLPurifier_AttrDef_Host extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * Instances of HTMLPurifier_AttrDef_IPv4 and HTMLPurifier_AttrDef_IPv6
+     */
     var $ipv4, $ipv6;
     
     function HTMLPurifier_AttrDef_Host() {

library/HTMLPurifier/AttrDef/ID.php

@@ -2,12 +2,15 @@
 
 require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/IDAccumulator.php';
-        
-// NOTE QUIRKY BEHAVIOR: even though this is the id processor, it
-// will ignore directive Attr:IDBlacklist, since it will only
-// go according to the ID accumulator. Since the accumulator is
-// automatically generated, it will have already absorbed the
-// blacklist. If you're hacking around, make sure you use load()!
+
+/**
+ * Validates the HTML attribute ID.
+ * @warning Even though this is the id processor, it
+ *          will ignore the directive Attr:IDBlacklist, since it will only
+ *          go according to the ID accumulator. Since the accumulator is
+ *          automatically generated, it will have already absorbed the
+ *          blacklist. If you're hacking around, make sure you use load()!
+ */
 
 class HTMLPurifier_AttrDef_ID extends HTMLPurifier_AttrDef
 {

library/HTMLPurifier/AttrDef/IPv4.php

@@ -2,12 +2,17 @@
 
 require_once 'HTMLPurifier/AttrDef.php';
 
-// spliced from Feyd's IPv6 function (pd)
-
+/**
+ * Validates an IPv4 address
+ * @author Feyd @ forums.devnetwork.net (public domain)
+ */
 class HTMLPurifier_AttrDef_IPv4 extends HTMLPurifier_AttrDef
 {
     
-    // regex is public so that IPv6 can reuse it
+    /**
+     * IPv4 regex, protected so that IPv6 can reuse it
+     * @protected
+     */
     var $ip4;
     
     function HTMLPurifier_AttrDef_IPv4() {

library/HTMLPurifier/AttrDef/IPv6.php

@@ -2,11 +2,12 @@
 
 require_once 'HTMLPurifier/AttrDef/IPv4.php';
 
-// IPv6 by Feyd, source is in public domain
-
-// note that this expects the brackets to be removed from IPv6 addresses
-// extends from the IPv4 impl. so we can borrow its regex
-
+/**
+ * Validates an IPv6 address.
+ * @author Feyd @ forums.devnetwork.net (public domain)
+ * @note This function requires brackets to have been removed from address
+ *       in URI.
+ */
 class HTMLPurifier_AttrDef_IPv6 extends HTMLPurifier_AttrDef_IPv4
 {
     

library/HTMLPurifier/AttrDef/Integer.php

@@ -2,14 +2,24 @@
 
 require_once 'HTMLPurifier/AttrDef.php';
 
-// appears to be a dud class: no currently allowed CSS uses this type
-// Uses this: widows, orphans, z-index, counter-increment, counter-reset
-
+/**
+ * Validates an integer.
+ * @note While this class was modeled off the CSS definition, no currently
+ *       allowed CSS uses this type.  The properties that do are: widows,
+ *       orphans, z-index, counter-increment, counter-reset.  Some of the
+ *       HTML attributes, however, find use for a non-negative version of this.
+ */
 class HTMLPurifier_AttrDef_Integer extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * Bool indicating whether or not integers can only be positive.
+     */
     var $non_negative = false;
     
+    /**
+     * @param $non_negative bool indicating whether or not only positive
+     */
     function HTMLPurifier_AttrDef_Integer($non_negative = false) {
         $this->non_negative = $non_negative;
     }

library/HTMLPurifier/AttrDef/Lang.php

@@ -2,8 +2,10 @@
 
 require_once 'HTMLPurifier/AttrDef.php';
 
-// built according to RFC 3066, which obsoleted RFC 1766
-
+/**
+ * Validates the HTML attribute lang, effectively a language code.
+ * @note Built according to RFC 3066, which obsoleted RFC 1766
+ */
 class HTMLPurifier_AttrDef_Lang extends HTMLPurifier_AttrDef
 {
     

library/HTMLPurifier/AttrDef/MultiLength.php

@@ -3,6 +3,12 @@
 require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/AttrDef/Length.php';
 
+/**
+ * Validates a MultiLength as defined by the HTML spec.
+ * 
+ * A multilength is either a integer (pixel count), a percentage, or
+ * a relative number.
+ */
 class HTMLPurifier_AttrDef_MultiLength extends HTMLPurifier_AttrDef_Length
 {
     

library/HTMLPurifier/AttrDef/Multiple.php

@@ -2,12 +2,30 @@
 
 require_once 'HTMLPurifier/AttrDef.php';
 
+/**
+ * Framework class for strings that involve multiple values.
+ * 
+ * Certain CSS properties such as border-width and margin allow multiple
+ * lengths to be specified.  This class can take a vanilla border-width
+ * definition and multiply it, usually into a max of four.
+ */
 class HTMLPurifier_AttrDef_Multiple extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * Instance of component definition to defer validation to.
+     */
     var $single;
+    
+    /**
+     * Max number of values allowed.
+     */
     var $max;
     
+    /**
+     * @param $single HTMLPurifier_AttrDef to multiply
+     * @param $max Max number of values allowed (usually four)
+     */
     function HTMLPurifier_AttrDef_Multiple($single, $max = 4) {
         $this->single = $single;
         $this->max = $max;

library/HTMLPurifier/AttrDef/Number.php

@@ -1,10 +1,19 @@
 <?php
 
+/**
+ * Validates a number as defined by the CSS spec.
+ */
 class HTMLPurifier_AttrDef_Number extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * Bool indicating whether or not only positive values allowed.
+     */
     var $non_negative = false;
     
+    /**
+     * @param $non_negative Bool indicating whether negatives are forbidden
+     */
     function HTMLPurifier_AttrDef_Number($non_negative = false) {
         $this->non_negative = $non_negative;
     }

library/HTMLPurifier/AttrDef/NumberSpan.php

@@ -1,23 +0,0 @@
-<?php
-
-require_once 'HTMLPurifier/AttrDef.php';
-
-// for col and row spans, essentially, a positive integer
-class HTMLPurifier_AttrDef_NumberSpan extends HTMLPurifier_AttrDef
-{
-    
-    function validate($string, $config, &$context) {
-        
-        $string = trim($string);
-        if ($string === '') return false;
-        if ($string === '1') return false; // this is the default value
-        if (!is_numeric($string)) return false;
-        $int = (int) $string;
-        if ($int <= 0) return false;
-        return (string) $int;
-        
-    }
-    
-}
-
-?>

library/HTMLPurifier/AttrDef/Percentage.php

@@ -3,11 +3,21 @@
 require_once 'HTMLPurifier/AttrDef.php';
 require_once 'HTMLPurifier/AttrDef/Number.php';
 
+/**
+ * Validates a Percentage as defined by the HTML spec.
+ * @note This also allows integer pixel values.
+ */
 class HTMLPurifier_AttrDef_Percentage extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * Instance of HTMLPurifier_AttrDef_Number to defer pixel validation
+     */
     var $number_def;
     
+    /**
+     * @param Bool indicating whether to forbid negative values
+     */
     function HTMLPurifier_AttrDef_Percentage($non_negative = false) {
         $this->number_def = new HTMLPurifier_AttrDef_Number($non_negative);
     }

library/HTMLPurifier/AttrDef/Pixels.php

@@ -2,6 +2,9 @@
 
 require_once 'HTMLPurifier/AttrDef.php';
 
+/**
+ * Validates an integer representation of pixels according to the HTML spec.
+ */
 class HTMLPurifier_AttrDef_Pixels extends HTMLPurifier_AttrDef
 {
     

library/HTMLPurifier/AttrDef/Text.php

@@ -2,6 +2,9 @@
 
 require_once 'HTMLPurifier/AttrDef.php';
 
+/**
+ * Validates arbitrary text according to the HTML spec.
+ */
 class HTMLPurifier_AttrDef_Text extends HTMLPurifier_AttrDef
 {
     

library/HTMLPurifier/AttrDef/TextDecoration.php

@@ -2,9 +2,18 @@
 
 require_once 'HTMLPurifier/AttrDef.php';
 
+/**
+ * Validates the value for the CSS property text-decoration
+ * @note This class could be generalized into a version that acts sort of
+ *       like Enum except you can compound the allowed values.
+ */
 class HTMLPurifier_AttrDef_TextDecoration extends HTMLPurifier_AttrDef
 {
     
+    /**
+     * Lookup table of allowed values.
+     * @protected
+     */
     var $allowed_values = array(
         'line-through' => true,
         'overline' => true,

library/HTMLPurifier/AttrDef/URI.php

@@ -11,6 +11,10 @@ HTMLPurifier_ConfigDef::define(
     'select the proper object validator when no scheme information is present.'
 );
 
+/**
+ * Validates a URI as defined by RFC 3986.
+ * @note Scheme-specific mechanics deferred to HTMLPurifier_URIScheme
+ */
 class HTMLPurifier_AttrDef_URI extends HTMLPurifier_AttrDef
 {
     

library/HTMLPurifier/HTMLDefinition.php

@@ -9,7 +9,7 @@ require_once 'HTMLPurifier/AttrDef.php';
     require_once 'HTMLPurifier/AttrDef/Pixels.php';
     require_once 'HTMLPurifier/AttrDef/Length.php';
     require_once 'HTMLPurifier/AttrDef/MultiLength.php';
-    require_once 'HTMLPurifier/AttrDef/NumberSpan.php';
+    require_once 'HTMLPurifier/AttrDef/Integer.php';
     require_once 'HTMLPurifier/AttrDef/URI.php';
     require_once 'HTMLPurifier/AttrDef/CSS.php';
 require_once 'HTMLPurifier/AttrTransform.php';
@@ -331,7 +331,7 @@ class HTMLPurifier_HTMLDefinition
         $this->info['col']->attr['width'] =
         $this->info['colgroup']->attr['width'] = $e_MultiLength;
         
-        $e__NumberSpan = new HTMLPurifier_AttrDef_NumberSpan();
+        $e__NumberSpan = new HTMLPurifier_AttrDef_Integer(true);
         $this->info['colgroup']->attr['span'] =
         $this->info['col']->attr['span']   =
         $this->info['td']->attr['rowspan'] =

tests/HTMLPurifier/AttrDef/NumberSpanTest.php

@@ -1,28 +0,0 @@
-<?php
-
-require_once 'HTMLPurifier/AttrDefHarness.php';
-require_once 'HTMLPurifier/AttrDef/NumberSpan.php';
-
-class HTMLPurifier_AttrDef_NumberSpanTest extends HTMLPurifier_AttrDefHarness
-{
-    
-    function test() {
-        
-        $this->def = new HTMLPurifier_AttrDef_NumberSpan();
-        
-        // this one requires a little explanation. A colspan="1" shouldn't
-        // exist at all: it's just a dud, since the default value is already
-        // supplied
-        $this->assertDef('1', false);
-        
-        $this->assertDef('4');
-        $this->assertDef('4.5', '4'); // round down (truncate)
-        $this->assertDef('0', false);
-        $this->assertDef('-4', false);
-        $this->assertDef('asdf', false);
-        
-    }
-    
-}
-
-?>

tests/index.php

@@ -61,7 +61,6 @@ $test_files[] = 'AttrDef/TextTest.php';
 $test_files[] = 'AttrDef/LangTest.php';
 $test_files[] = 'AttrDef/PixelsTest.php';
 $test_files[] = 'AttrDef/LengthTest.php';
-$test_files[] = 'AttrDef/NumberSpanTest.php';
 $test_files[] = 'AttrDef/URITest.php';
 $test_files[] = 'AttrDef/CSSTest.php';
 $test_files[] = 'AttrDef/CompositeTest.php';