Document core classes up to EntityLookup.php

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

library/HTMLPurifier/CSSDefinition.php

@@ -9,11 +9,24 @@ require_once 'HTMLPurifier/AttrDef/Multiple.php';
 require_once 'HTMLPurifier/AttrDef/TextDecoration.php';
 require_once 'HTMLPurifier/AttrDef/FontFamily.php';
 
+/**
+ * Defines allowed CSS attributes and what their values are.
+ * @see HTMLPurifier_HTMLDefinition
+ */
 class HTMLPurifier_CSSDefinition
 {
     
+    /**
+     * Assoc array of attribute name to definition object.
+     */
     var $info = array();
     
+    /**
+     * Returns sole instance of this definition.
+     * @param $prototype Optional prototype you may pass in to overload
+     *        the sole instance.  Good for replacing an instance of
+     *        the object with your own, custom object.
+     */
     function &instance($prototype = null) {
         static $instance = null;
         if ($prototype) {
@@ -25,8 +38,9 @@ class HTMLPurifier_CSSDefinition
         return $instance;
     }
     
-    function HTMLPurifier_CSSDefinition() {}
+    /**
-    
+     * Constructs the info array.  The meat of this class.
+     */
     function setup() {
         
         $this->info['text-align'] = new HTMLPurifier_AttrDef_Enum(

library/HTMLPurifier/ChildDef.php

@@ -22,27 +22,73 @@ HTMLPurifier_ConfigDef::define(
 );
 
 /**
- * Class that defines allowed child nodes and validates tokens against this.
+ * Defines allowed child nodes and validates tokens against it.
  */
 class HTMLPurifier_ChildDef
 {
+    /**
+     * Type of child definition, usually right-most part of class name lowercase
+     * 
+     * Used occasionally in terms of context.  Possible values include
+     * custom, required, optional and empty.
+     */
     var $type;
+    
+    /**
+     * Bool that indicates whether or not an empty array of children is okay
+     * 
+     * This is necessary for redundant checking when changes affecting
+     * a child node may cause a parent node to now be disallowed.
+     */
     var $allow_empty;
-    function validateChildren($tokens_of_children) {
+    
+    /**
+     * Validates nodes according to definition and returns modification.
+     * 
+     * @warning $context is NOT HTMLPurifier_AttrContext
+     * @param $tokens_of_children Array of HTMLPurifier_Token
+     * @param $config HTMLPurifier_Config object
+     * @param $context String context indicating inline, block or unknown
+     * @return bool true to leave nodes as is
+     * @return bool false to remove parent node
+     * @return array of replacement child tokens
+     */
+    function validateChildren($tokens_of_children, $config, $context) {
         trigger_error('Call to abstract function', E_USER_ERROR);
     }
 }
 
+/**
+ * Custom validation class, accepts DTD child definitions
+ * 
+ * @warning Currently this class is an all or nothing proposition, that is,
+ *          it will only give a bool return value.  Table is the only
+ *          child definition that uses this class, and we ought to give
+ *          it a dedicated one.
+ */
 class HTMLPurifier_ChildDef_Custom extends HTMLPurifier_ChildDef
 {
     var $type = 'custom';
     var $allow_empty = false;
+    /**
+     * Allowed child pattern as defined by the DTD
+     */
     var $dtd_regex;
+    /**
+     * PCRE regex derived from $dtd_regex
+     * @private
+     */
     var $_pcre_regex;
+    /**
+     * @param $dtd_regex Allowed child pattern from the DTD
+     */
     function HTMLPurifier_ChildDef_Custom($dtd_regex) {
         $this->dtd_regex = $dtd_regex;
         $this->_compileRegex();
     }
+    /**
+     * Compiles the PCRE regex from a DTD regex ($dtd_regex to $_pcre_regex)
+     */
     function _compileRegex() {
         $raw = str_replace(' ', '', $this->dtd_regex);
         if ($raw{0} != '(') {
@@ -82,9 +128,18 @@ class HTMLPurifier_ChildDef_Custom extends HTMLPurifier_ChildDef
     }
 }
 
+/**
+ * Definition that allows a set of elements, but disallows empty children.
+ */
 class HTMLPurifier_ChildDef_Required extends HTMLPurifier_ChildDef
 {
+    /**
+     * Lookup table of allowed elements.
+     */
     var $elements = array();
+    /**
+     * @param $elements List of allowed element names (lowercase).
+     */
     function HTMLPurifier_ChildDef_Required($elements) {
         if (is_string($elements)) {
             $elements = str_replace(' ', '', $elements);
@@ -168,8 +223,13 @@ class HTMLPurifier_ChildDef_Required extends HTMLPurifier_ChildDef
     }
 }
 
-// only altered behavior is that it returns an empty array
+/**
-// instead of a false (to delete the node)
+ * Definition that allows a set of elements, and allows no children.
+ * @note This is a hack to reuse code from HTMLPurifier_ChildDef_Required,
+ *       really, one shouldn't inherit from the other.  Only altered behavior
+ *       is to overload a returned false with an array.  Thus, it will never
+ *       return false.
+ */
 class HTMLPurifier_ChildDef_Optional extends HTMLPurifier_ChildDef_Required
 {
     var $allow_empty = true;
@@ -181,23 +241,48 @@ class HTMLPurifier_ChildDef_Optional extends HTMLPurifier_ChildDef_Required
     }
 }
 
-// placeholder
+/**
+ * Definition that disallows all elements.
+ * @warning validateChildren() in this class is actually never called, because
+ *          empty elements are corrected in HTMLPurifier_Strategy_MakeWellFormed
+ *          before child definitions are parsed in earnest by
+ *          HTMLPurifier_Strategy_FixNesting.
+ */
 class HTMLPurifier_ChildDef_Empty extends HTMLPurifier_ChildDef
 {
     var $allow_empty = true;
     var $type = 'empty';
     function HTMLPurifier_ChildDef_Empty() {}
     function validateChildren($tokens_of_children, $config, $context) {
-        return false;
+        return array();
     }
 }
 
+/**
+ * Definition that uses different definitions depending on context.
+ * 
+ * The del and ins tags are notable because they allow different types of
+ * elements depending on whether or not they're in a block or inline context.
+ * Chameleon allows this behavior to happen by using two different
+ * definitions depending on context.  While this somewhat generalized,
+ * it is specifically intended for those two tags.
+ */
 class HTMLPurifier_ChildDef_Chameleon extends HTMLPurifier_ChildDef
 {
     
+    /**
+     * Instance of the definition object to use when inline. Usually stricter.
+     */
     var $inline;
+    /**
+     * Instance of the definition object to use when block.
+     */
     var $block;
     
+    /**
+     * @param $inline List of elements to allow when inline.
+     * @param $block List of elements to allow when block.
+     */
     function HTMLPurifier_ChildDef_Chameleon($inline, $block) {
         $this->inline = new HTMLPurifier_ChildDef_Optional($inline);
         $this->block  = new HTMLPurifier_ChildDef_Optional($block);

library/HTMLPurifier/Config.php

@@ -1,7 +1,10 @@
 <?php
 
 /**
+ * Configuration object that triggers customizable behavior.
  *
+ * @warning This class is strongly defined: that means that the class
+ *          will fail if an undefined directive is retrieved or set.
  * 
  * @note Many classes that could (although many times don't) use the
  *       configuration object make it a mandatory parameter.  This is
@@ -12,18 +15,34 @@
 class HTMLPurifier_Config
 {
     
+    /**
+     * Two-level associative array of configuration directives
+     */
     var $conf;
     
+    /**
+     * @param $definition HTMLPurifier_ConfigDef that defines what directives
+     *                    are allowed.
+     */
     function HTMLPurifier_Config(&$definition) {
         $this->conf = $definition->info; // set up the defaults
     }
     
+    /**
+     * Convenience constructor that creates a default configuration object.
+     * @return Default HTMLPurifier_Config object.
+     */
     function createDefault() {
         $definition =& HTMLPurifier_ConfigDef::instance();
         $config = new HTMLPurifier_Config($definition);
         return $config;
     }
     
+    /**
+     * Retreives a value from the configuration.
+     * @param $namespace String namespace
+     * @param $key String key
+     */
     function get($namespace, $key) {
         if (!isset($this->conf[$namespace][$key])) {
             trigger_error('Cannot retrieve value of undefined directive',
@@ -33,6 +52,12 @@ class HTMLPurifier_Config
         return $this->conf[$namespace][$key];
     }
     
+    /**
+     * Sets a value to configuration.
+     * @param $namespace String namespace
+     * @param $key String key
+     * @param $value Mixed value
+     */
     function set($namespace, $key, $value) {
         if (!isset($this->conf[$namespace][$key])) {
             trigger_error('Cannot set undefined directive to value',

library/HTMLPurifier/ConfigDef.php

@@ -1,15 +1,29 @@
 <?php
 
+/**
+ * Configuration definition, defines directives and their defaults.
+ * @todo Build documentation generation capabilities.
+ */
 class HTMLPurifier_ConfigDef {
     
+    /**
+     * Currently defined directives (and namespaces).
+     * @note This shares the exact same structure as HTMLPurifier_Config::$conf
+     */
     var $info = array();
     
+    /**
+     * Initializes the default namespaces.
+     */
     function initialize() {
         $this->defineNamespace('Core', 'Core features that are always available.');
         $this->defineNamespace('Attr', 'Features regarding attribute validation.');
         $this->defineNamespace('URI', 'Features regarding Uniform Resource Identifiers.');
     }
     
+    /**
+     * Retrieves an instance of the application-wide configuration definition.
+     */
     function &instance($prototype = null) {
         static $instance;
         if ($prototype !== null) {
@@ -21,6 +35,17 @@ class HTMLPurifier_ConfigDef {
         return $instance;
     }
     
+    /**
+     * Defines a directive for configuration
+     * @warning Will fail of directive's namespace is defined
+     * @todo Collect information on description and allow redefinition
+     *       so that multiple files can register a dependency on a
+     *       configuration directive.
+     * @param $namespace Namespace the directive is in
+     * @param $name Key of directive
+     * @param $default Default value of directive
+     * @param $description Description of directive for documentation
+     */
     function define($namespace, $name, $default, $description) {
         $def =& HTMLPurifier_ConfigDef::instance();
         if (!isset($def->info[$namespace])) {
@@ -36,6 +61,11 @@ class HTMLPurifier_ConfigDef {
         $def->info[$namespace][$name] = $default;
     }
     
+    /**
+     * Defines a namespace for directives to be put into.
+     * @param $namespace Namespace's name
+     * @param $description Description of the namespace
+     */
     function defineNamespace($namespace, $description) {
         $def =& HTMLPurifier_ConfigDef::instance();
         if (isset($def->info[$namespace])) {

library/HTMLPurifier/EntityLookup.php

@@ -1,12 +1,22 @@
 <?php
 
+/**
+ * Object that provides entity lookup table from entity name to character
+ */
 class HTMLPurifier_EntityLookup {
     
+    /**
+     * Assoc array of entity name to character represented.
+     * @public
+     */
     var $table;
     
-    function HTMLPurifier_EntityLookup() {}
+    /**
-    
+     * Sets up the entity lookup table from the serialized file contents.
-    // to enforce Singleton-ness
+     * @note The serialized contents are versioned, but were generated
+     *       using the maintenance script generate_entity_file.php
+     * @warning This is not in constructor to help enforce the Singleton
+     */
     function setup($file = false) {
         if (!$file) {
             $file = dirname(__FILE__) . '/EntityLookup/data.txt';
@@ -14,6 +24,10 @@ class HTMLPurifier_EntityLookup {
         $this->table = unserialize(file_get_contents($file));
     }
     
+    /**
+     * Retrieves sole instance of the object.
+     * @param Optional prototype of custom lookup table to overload with.
+     */
     function instance($prototype = false) {
         // no references, since PHP doesn't copy unless modified
         static $instance = null;