Finish documentation for all base classes.

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

library/HTMLPurifier/Generator.php

@@ -15,16 +15,29 @@ HTMLPurifier_ConfigDef::define(
     'generateFromTokens.'
 );
 
+/**
+ * Generates HTML from tokens.
+ */
 class HTMLPurifier_Generator
 {
     
-    var $clean_utf8 = false;
+    /**
+     * Bool cache of the CleanUTF8DuringGeneration directive.
+     * @private
+     */
+    var $_clean_utf8 = false;
     
-    // only unit tests may omit configuration: internals MUST pass config
+    /**
+     * Generates HTML from an array of tokens.
+     * @param $tokens Array of HTMLPurifier_Token
+     * @param $config HTMLPurifier_Config object
+     * @return Generated HTML
+     * @note Only unit tests may omit configuration: internals MUST pass config
+     */
     function generateFromTokens($tokens, $config = null) {
         $html = '';
         if (!$config) $config = HTMLPurifier_Config::createDefault();
-        $this->clean_utf8 = $config->get('Core', 'CleanUTF8DuringGeneration');
+        $this->_clean_utf8 = $config->get('Core', 'CleanUTF8DuringGeneration');
         if (!$tokens) return '';
         foreach ($tokens as $token) {
             $html .= $this->generateFromToken($token);
@@ -32,6 +45,11 @@ class HTMLPurifier_Generator
         return $html;
     }
     
+    /**
+     * Generates HTML from a single token.
+     * @param $token HTMLPurifier_Token object.
+     * @return Generated HTML
+     */
     function generateFromToken($token) {
         if (!isset($token->type)) return '';
         if ($token->type == 'start') {
@@ -54,6 +72,11 @@ class HTMLPurifier_Generator
         }
     }
     
+    /**
+     * Generates attribute declarations from attribute array.
+     * @param $assoc_array_of_attributes Attribute array
+     * @return Generate HTML fragment for insertion.
+     */
     function generateAttributes($assoc_array_of_attributes) {
         $html = '';
         foreach ($assoc_array_of_attributes as $key => $value) {
@@ -62,8 +85,13 @@ class HTMLPurifier_Generator
         return rtrim($html);
     }
     
+    /**
+     * Escapes raw text data.
+     * @param $string String data to escape for HTML.
+     * @return String escaped data.
+     */
     function escape($string) {
-        if ($this->clean_utf8) $string = HTMLPurifier_Lexer::cleanUTF8($string);
+        if ($this->_clean_utf8) $string = HTMLPurifier_Lexer::cleanUTF8($string);
         return htmlspecialchars($string, ENT_COMPAT, 'UTF-8');
     }
     

library/HTMLPurifier/HTMLDefinition.php

@@ -30,12 +30,8 @@ require_once 'HTMLPurifier/TagTransform.php';
  * each allowed element. It also contains special use information (always
  * prefixed by info) for intelligent tag closing and global attributes.
  * 
- * Planned improvements include attribute transformation objects as well as
- * migration of auto-tag-closing from HTMLPurifier_Strategy_MakeWellFormed
- * (these can likely just be extensions of ElementDef).
- * 
- * After development drops off, the definition generation will be moved to
- * a maintenance script and we will stipulate that definition be created
+ * For optimization, the definition generation may be moved to
+ * a maintenance script and stipulate that definition be created
  * by a factory method that unserializes a serialized version of Definition.
  * Customization would entail copying the maintenance script, making the
  * necessary changes, generating the serialized object, and then hooking it
@@ -46,26 +42,50 @@ require_once 'HTMLPurifier/TagTransform.php';
 class HTMLPurifier_HTMLDefinition
 {
     
+    /**
+     * Associative array of element names to HTMLPurifier_ElementDef
+     * @public
+     */
     var $info = array();
     
-    // used solely by HTMLPurifier_Strategy_ValidateAttributes
+    /**
+     * Associative array of global attribute name to attribute definition.
+     * @public
+     */
     var $info_global_attr = array();
     
-    // used solely by HTMLPurifier_Strategy_FixNesting
+    /**
+     * String name of parent element HTML will be going into.
+     * @public
+     */
     var $info_parent = 'div';
     
-    // used solely by HTMLPurifier_Strategy_RemoveForeignElements
+    /**
+     * Associative array of deprecated tag name to HTMLPurifier_TagTransform
+     * @public
+     */
     var $info_tag_transform = array();
     
-    // used solely by HTMLPurifier_Strategy_ValidateAttributes
+    /**
+     * List of HTMLPurifier_AttrTransform to be performed before validation.
+     * @public
+     */
     var $info_attr_transform_pre = array();
+    
+    /**
+     * List of HTMLPurifier_AttrTransform to be performed after validation/
+     * @public
+     */
     var $info_attr_transform_post = array();
     
-    // WARNING! Prototype is not passed by reference, so in order to get
-    // a copy of the real one, you'll have to destroy your copy and
-    // use instance() to get it.
-    // Usually, however, modifying the returned definition (reference) should be
-    // sufficient
+    /**
+     * Retrieve sole instance of definition object.
+     * @param $prototype Optional prototype to overload instance with.
+     * @warning Prototype is not passed by reference, so in order to get
+     *          a copy of the real one, you'll have to destroy your copy
+     *          and use instance() to get it.  We strongly recommend modifying
+     *          the default returned definition instead.
+     */
     function &instance($prototype = null) {
         static $instance = null;
         if ($prototype) {
@@ -77,8 +97,9 @@ class HTMLPurifier_HTMLDefinition
         return $instance;
     }
     
-    function HTMLPurifier_HTMLDefinition() {}
-    
+    /**
+     * Initializes the definition, the meat of the class.
+     */
     function setup() {
         
         // emulates the structure of the DTD
@@ -130,6 +151,7 @@ class HTMLPurifier_HTMLDefinition
         $e_misc = "$e_misc_inline";
         $e_inline = "a | $e_special | $e_fontstyle | $e_phrase".
           " | $e_inline_forms";
+        // pseudo-property we created for convenience, see later on
         $e__inline = "#PCDATA | $e_inline | $e_misc_inline";
         // note the casing
         $e_Inline = new HTMLPurifier_ChildDef_Optional($e__inline);
@@ -394,15 +416,52 @@ class HTMLPurifier_HTMLDefinition
     
 }
 
+/**
+ * Structure that stores an element definition.
+ */
 class HTMLPurifier_ElementDef
 {
     
+    /**
+     * Associative array of attribute name to HTMLPurifier_AttrDef
+     * @public
+     */
     var $attr = array();
+    
+    /**
+     * List of tag's HTMLPurifier_AttrTransform to be done before validation
+     * @public
+     */
     var $attr_transform_pre = array();
+    
+    /**
+     * List of tag's HTMLPurifier_AttrTransform to be done after validation
+     * @public
+     */
     var $attr_transform_post = array();
+    
+    /**
+     * Lookup table of tags that close this tag.
+     * @public
+     */
     var $auto_close = array();
+    
+    /**
+     * HTMLPurifier_ChildDef of this tag.
+     * @public
+     */
     var $child;
+    
+    /**
+     * Type of the tag: inline or block or unknown?
+     * @public
+     */
     var $type = 'unknown';
+    
+    /**
+     * Lookup table of tags excluded from all descendants of this tag.
+     * @public
+     */
     var $excludes = array();
     
 }

library/HTMLPurifier/IDAccumulator.php

@@ -1,15 +1,33 @@
 <?php
 
+/**
+ * Component of HTMLPurifier_AttrContext that accumulates IDs to prevent dupes
+ * @note In Slashdot-speak, dupe means duplicate.
+ */
 class HTMLPurifier_IDAccumulator
 {
     
+    /**
+     * Lookup table of IDs we've accumulated.
+     * @public
+     */
     var $ids = array();
     
+    /**
+     * Add an ID to the lookup table.
+     * @param $id ID to be added.
+     * @return Bool status, true if success, false if there's a dupe
+     */
     function add($id) {
         if (isset($this->ids[$id])) return false;
         return $this->ids[$id] = true;
     }
     
+    /**
+     * Load a list of IDs into the lookup table
+     * @param $array_of_ids Array of IDs to load
+     * @note This function doesn't care about duplicates
+     */
     function load($array_of_ids) {
         foreach ($array_of_ids as $id) {
             $this->ids[$id] = true;

library/HTMLPurifier/TagTransform.php

@@ -2,20 +2,37 @@
 
 require_once('HTMLPurifier/Token.php');
 
+/**
+ * Defines a mutation of an obsolete tag into a valid tag.
+ */
 class HTMLPurifier_TagTransform
 {
     
+    /**
+     * Tag name to transform the tag to.
+     * @public
+     */
+    var $transform_to;
+    
+    /**
+     * Transforms the obsolete tag into the valid tag.
+     * @param $tag Tag to be transformed.
+     */
     function transform($tag) {
         trigger_error('Call to abstract function', E_USER_ERROR);
     }
     
 }
 
+/**
+ * Simple transformation, just change tag name to something else.
+ */
 class HTMLPurifier_TagTransform_Simple extends HTMLPurifier_TagTransform
 {
     
-    var $transform_to;
-    
+    /**
+     * @param $transform_to Tag name to transform to.
+     */
     function HTMLPurifier_TagTransform_Simple($transform_to) {
         $this->transform_to = $transform_to;
     }
@@ -28,6 +45,12 @@ class HTMLPurifier_TagTransform_Simple extends HTMLPurifier_TagTransform
     
 }
 
+/**
+ * Transforms CENTER tags into proper version (DIV with text-align CSS)
+ * 
+ * Takes a CENTER tag, parses the align attribute, and then if it's valid
+ * assigns it to the CSS property text-align.
+ */
 class HTMLPurifier_TagTransform_Center extends HTMLPurifier_TagTransform
 {
     var $transform_to = 'div';
@@ -51,6 +74,18 @@ class HTMLPurifier_TagTransform_Center extends HTMLPurifier_TagTransform
     }
 }
 
+/**
+ * Transforms FONT tags to the proper form (SPAN with CSS styling)
+ * 
+ * This transformation takes the three proprietary attributes of FONT and
+ * transforms them into their corresponding CSS attributes.  These are color,
+ * face, and size.
+ * 
+ * @note Size is an interesting case because it doesn't map cleanly to CSS.
+ *       Thanks to
+ *       http://style.cleverchimp.com/font_size_intervals/altintervals.html
+ *       for reasonable mappings.
+ */
 class HTMLPurifier_TagTransform_Font extends HTMLPurifier_TagTransform
 {
     
@@ -78,8 +113,6 @@ class HTMLPurifier_TagTransform_Font extends HTMLPurifier_TagTransform
             return $new_tag;
         }
         
-        // font size lookup table based off of:
-        //  http://style.cleverchimp.com/font_size_intervals/altintervals.html
         $attributes = $tag->attributes;
         $prepend_style = '';
         

library/HTMLPurifier/Token.php

@@ -11,6 +11,14 @@
  */
 class HTMLPurifier_Token {
     var $type; /**< Type of node to bypass <tt>is_a()</tt>. @public */
+    
+    /**
+     * Copies the tag into a new one (clone substitute).
+     * @return Copied token
+     */
+    function copy() {
+        trigger_error('Cannot copy abstract class', E_USER_ERROR);
+    }
 }
 
 /**

library/HTMLPurifier/TokenFactory.php

@@ -2,12 +2,30 @@
 
 require_once 'HTMLPurifier/Token.php';
 
+/**
+ * Factory for token generation (PHP 5 only).
+ * 
+ * @note Doing some benchmarking indicates that the new operator is much
+ *       slower than the clone operator (even discounting the cost of the
+ *       constructor).  This class is for that optimization.  We may want to
+ *       consider porting this to PHP 4 by virtue of the fact it makes the code
+ *       easier to read.  Other then that, there's not much point as we don't
+ *       maintain parallel HTMLPurifier_Token hierarchies (the main reason why
+ *       you'd want to use an abstract factory).
+ */
 class HTMLPurifier_TokenFactory
 {
     
+    /**
+     * Prototypes that will be cloned.
+     * @private
+     */
     // p stands for prototype
     private $p_start, $p_end, $p_empty, $p_text, $p_comment;
     
+    /**
+     * Generates blank prototypes for cloning.
+     */
     public function __construct() {
         $this->p_start  = new HTMLPurifier_Token_Start('', array());
         $this->p_end    = new HTMLPurifier_Token_End('');
@@ -16,30 +34,57 @@ class HTMLPurifier_TokenFactory
         $this->p_comment= new HTMLPurifier_Token_Comment('');
     }
     
+    /**
+     * Creates a HTMLPurifier_Token_Start.
+     * @param $name Tag name
+     * @param $attribute Associative array of attributes
+     * @return Generated HTMLPurifier_Token_Start
+     */
     public function createStart($name, $attributes = array()) {
         $p = clone $this->p_start;
         $p->HTMLPurifier_Token_Tag($name, $attributes);
         return $p;
     }
     
+    /**
+     * Creates a HTMLPurifier_Token_End.
+     * @param $name Tag name
+     * @return Generated HTMLPurifier_Token_End
+     */
     public function createEnd($name) {
         $p = clone $this->p_end;
         $p->HTMLPurifier_Token_Tag($name);
         return $p;
     }
     
+    /**
+     * Creates a HTMLPurifier_Token_Empty.
+     * @param $name Tag name
+     * @param $attribute Associative array of attributes
+     * @return Generated HTMLPurifier_Token_Empty
+     */s
     public function createEmpty($name, $attributes = array()) {
         $p = clone $this->p_empty;
         $p->HTMLPurifier_Token_Tag($name, $attributes);
         return $p;
     }
     
+    /**
+     * Creates a HTMLPurifier_Token_Text.
+     * @param $data Data of text token
+     * @return Generated HTMLPurifier_Token_Text
+     */
     public function createText($data) {
         $p = clone $this->p_text;
         $p->HTMLPurifier_Token_Text($data);
         return $p;
     }
     
+    /**
+     * Creates a HTMLPurifier_Token_Comment.
+     * @param $data Data of comment token
+     * @return Generated HTMLPurifier_Token_Comment
+     */
     public function createComment($data) {
         $p = clone $this->p_comment;
         $p->HTMLPurifier_Token_Comment($data);

library/HTMLPurifier/URIScheme.php

@@ -1,10 +1,29 @@
 <?php
 
+/**
+ * Validator for the components of a URI for a specific scheme
+ */
 class HTMLPurifier_URIScheme
 {
     
+    /**
+     * Scheme's default port (integer)
+     * @public
+     */
     var $default_port = null;
     
+    /**
+     * Validates the components of a URI
+     * @note This implementation should be called by children if they define
+     *       a default port, as it does port processing.
+     * @note Fragment is omitted as that is scheme independent
+     * @param $userinfo User info found before at sign in authority
+     * @param $host Hostname in authority
+     * @param $port Port found after colon in authority
+     * @param $path Path of URI
+     * @param $query Query of URI, found after question mark
+     * @param $config HTMLPurifier_Config object
+     */
     function validateComponents(
         $userinfo, $host, $port, $path, $query, $config
     ) {

library/HTMLPurifier/URISchemeRegistry.php

@@ -24,12 +24,19 @@ HTMLPurifier_ConfigDef::define(
     'in order to add more schemes.'
 );
 
+/**
+ * Registry for retrieving specific URI scheme validator objects.
+ */
 class HTMLPurifier_URISchemeRegistry
 {
     
-    // pass a registry object $prototype with a compatible interface and
-    // the function will copy it and return it all further times.
-    // pass bool true to reset to the default registry
+    /**
+     * Retrieve sole instance of the registry.
+     * @param $prototype Optional prototype to overload sole instance with,
+     *                   or bool true to reset to default registry.
+     * @note Pass a registry object $prototype with a compatible interface and
+     *       the function will copy it and return it all further times.
+     */
     function &instance($prototype = null) {
         static $instance = null;
         if ($prototype !== null) {
@@ -40,9 +47,23 @@ class HTMLPurifier_URISchemeRegistry
         return $instance;
     }
     
+    /**
+     * Cache of retrieved schemes.
+     * @protected
+     */
     var $schemes = array();
+    
+    /**
+     * Directory where scheme objects can be found
+     * @private
+     */
     var $_scheme_dir = null;
     
+    /**
+     * Retrieves a scheme validator object
+     * @param $scheme String scheme name like http or mailto
+     * @param $config HTMLPurifier_Config object
+     */
     function &getScheme($scheme, $config = null) {
         if (!$config) $config = HTMLPurifier_Config::createDefault();
         $null = null; // for the sake of passing by reference
@@ -67,6 +88,11 @@ class HTMLPurifier_URISchemeRegistry
         return $this->schemes[$scheme];
     }
     
+    /**
+     * Registers a custom scheme to the cache.
+     * @param $scheme Scheme name
+     * @param $scheme_obj HTMLPurifier_URIScheme object
+     */
     function register($scheme, &$scheme_obj) {
         $this->schemes[$scheme] =& $scheme_obj;
     }