Add lots of documentation.

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

library/HTMLPurifier.php

@@ -3,7 +3,7 @@
 /*!
  * @mainpage
  * 
- * HTMLPurifier is a purification class that will take an arbitrary snippet of
+ * HTMLPurifier is an HTML filter that will take an arbitrary snippet of
  * HTML and rigorously test, validate and filter it into a version that
  * is safe for output onto webpages. It achieves this by:
  * 
@@ -15,7 +15,10 @@
  *      -# Validating attributes of the nodes; and
  *  -# Generating HTML from the purified tokens.
  * 
- * See /docs/spec.txt for more details.
+ * However, most users will only need to interface with the HTMLPurifier
+ * class, so this massive amount of infrastructure is usually concealed.
+ * If you plan on working with the internals, be sure to include
+ * HTMLPurifier_ConfigDef and HTMLPurifier_Config.
  */
 
 require_once 'HTMLPurifier/ConfigDef.php';
@@ -37,29 +40,37 @@ class HTMLPurifier
     
     var $config;
     
+    var $lexer, $strategy, $generator;
+    
     /**
      * Initializes the purifier.
-     * @param $config Configuration for all instances of the purifier
+     * @param $config Optional HTMLPurifier_Config object for all instances of
+     *                the purifier, if omitted, a default configuration is
+     *                supplied.
      */
     function HTMLPurifier($config = null) {
         $this->config = $config ? $config : HTMLPurifier_Config::createDefault();
+        
+        $this->lexer = HTMLPurifier_Lexer::create();
+        $this->strategy = new HTMLPurifier_Strategy_Core();
+        $this->generator = new HTMLPurifier_Generator();
     }
     
     /**
-     * Purifies HTML.
+     * Filters an HTML snippet/document to be XSS-free and standards-compliant.
      * 
      * @param $html String of HTML to purify
-     * @param $config HTMLPurifier_Config object for this specific round
+     * @param $config HTMLPurifier_Config object for this operation, if omitted,
+     *                defaults to the config object specified during this
+     *                object's construction.
      * @return Purified HTML
      */
     function purify($html, $config = null) {
         $config = $config ? $config : $this->config;
-        $lexer = HTMLPurifier_Lexer::create();
+        return
-        $strategy = new HTMLPurifier_Strategy_Core();
+            $this->generator->generateFromTokens(
-        $generator = new HTMLPurifier_Generator();
+                $this->strategy->execute(
-        return $generator->generateFromTokens(
+                    $this->lexer->tokenizeHTML($html, $config),
-            $strategy->execute(
-                $lexer->tokenizeHTML($html, $config),
                 $config
             ),
             $config

library/HTMLPurifier/AttrContext.php

@@ -5,10 +5,21 @@
  * 
  * All it is is a data-structure that holds objects that accumulate state, like
  * HTMLPurifier_IDAccumulator.
+ * 
+ * @param Many functions that accept this object have it as a mandatory
+ *        parameter, even when there is no use for it.  Though this is
+ *        for the same reasons as why HTMLPurifier_Config is a mandatory
+ *        parameter, it is also because you cannot assign a default value
+ *        to a parameter passed by reference (passing by reference is essential
+ *        for context to work in PHP 4).
  */
 
 class HTMLPurifier_AttrContext
 {
+    /**
+     * Contains an HTMLPurifier_IDAccumulator, which keeps track of used IDs.
+     * @public
+     */
     var $id_accumulator;
 }
 

library/HTMLPurifier/AttrDef.php

@@ -2,15 +2,50 @@
 
 require_once 'HTMLPurifier/AttrContext.php';
 
-// AttrDef = Attribute Definition
+/**
+ * Base class for all validating attribute definitions.
+ * 
+ * This family of classes forms the core for not only HTML attribute validation,
+ * but also any sort of string that needs to be validated or cleaned (which
+ * means CSS properties and composite definitions are defined here too).  
+ * Besides defining (through code) what precisely makes the string valid,
+ * subclasses are also responsible for cleaning the code if possible.
+ */
+
 class HTMLPurifier_AttrDef
 {
-    function HTMLPurifier_AttrDef() {}
     
+    /**
+     * Abstract function defined for functions that validate and clean strings.
+     * 
+     * This function forms the basis for all the subclasses: they must
+     * define this method.
+     * 
+     * @public
+     * @param $string String to be validated and cleaned.
+     * @param $config Mandatory HTMLPurifier_Config object.
+     * @param $context Mandatory HTMLPurifier_AttrContext object.
+     */
     function validate($string, $config, &$context) {
         trigger_error('Cannot call abstract function', E_USER_ERROR);
     }
     
+    /**
+     * Convenience method that parses a string as if it were CDATA.
+     * 
+     * This method process a string in the manner specified at
+     * <http://www.w3.org/TR/html4/types.html#h-6.2> by removing
+     * leading and trailing whitespace, ignoring line feeds, and replacing
+     * carriage returns and tabs with spaces.  While most useful for HTML
+     * attributes specified as CDATA, it can also be applied to most CSS
+     * values.
+     * 
+     * @note This method is not entirely standards compliant, as trim() removes
+     *       more types of whitespace than specified in the spec. In practice,
+     *       this is rarely a problem.
+     * 
+     * @public
+     */
     function parseCDATA($string) {
         $string = trim($string);
         $string = str_replace("\n", '', $string);

library/HTMLPurifier/AttrTransform.php

@@ -1,12 +1,31 @@
 <?php
 
-// AttrTransform = Attribute Transformation, when handling one attribute
+/**
-//                 isn't enough
+ * Processes an entire attribute array for corrections needing multiple values.
+ * 
+ * Occasionally, a certain attribute will need to be removed and popped onto
+ * another value.  Instead of creating a complex return syntax for
+ * HTMLPurifier_AttrDef, we just pass the whole attribute array to a
+ * specialized object and have that do the special work.  That is the
+ * family of HTMLPurifier_AttrTransform.
+ * 
+ * An attribute transformation can be assigned to run before or after
+ * HTMLPurifier_AttrDef validation.  See HTMLPurifier_HTMLDefinition for
+ * more details.
+ */
+
 class HTMLPurifier_AttrTransform
 {
-    function HTMLPurifier_AttrTransform() {}
     
-    function transform($token, $config = null) {
+    /**
+     * Abstract: makes changes to the attributes dependent on multiple values.
+     * 
+     * @param $attr Assoc array of attributes, usually from
+     *              HTMLPurifier_Token_Tag::$attributes
+     * @param $config Mandatory HTMLPurifier_Config object.
+     * @returns Processed attribute array.
+     */
+    function transform($attr, $config) {
         trigger_error('Cannot call abstract function', E_USER_ERROR);
     }
 }

library/HTMLPurifier/AttrTransform/BdoDir.php

@@ -14,10 +14,10 @@ HTMLPurifier_ConfigDef::define(
 class HTMLPurifier_AttrTransform_BdoDir extends HTMLPurifier_AttrTransform
 {
     
-    function transform($attributes, $config) {
+    function transform($attr, $config) {
-        if (isset($attributes['dir'])) return $attributes;
+        if (isset($attr['dir'])) return $attributes;
-        $attributes['dir'] = $config->get('Attr', 'DefaultTextDir');
+        $attr['dir'] = $config->get('Attr', 'DefaultTextDir');
-        return $attributes;
+        return $attr;
     }
     
 }

library/HTMLPurifier/AttrTransform/ImgRequired.php

@@ -22,23 +22,23 @@ HTMLPurifier_ConfigDef::define(
 class HTMLPurifier_AttrTransform_ImgRequired extends HTMLPurifier_AttrTransform
 {
     
-    function transform($attributes, $config) {
+    function transform($attr, $config) {
         
         $src = true;
-        if (!isset($attributes['src'])) {
+        if (!isset($attr['src'])) {
-            $attributes['src'] = $config->get('Attr', 'DefaultInvalidImage');
+            $attr['src'] = $config->get('Attr', 'DefaultInvalidImage');
             $src = false;
         }
         
-        if (!isset($attributes['alt'])) {
+        if (!isset($attr['alt'])) {
             if ($src) {
-                $attributes['alt'] = basename($attributes['src']);
+                $attr['alt'] = basename($attr['src']);
             } else {
-                $attributes['alt'] = $config->get('Attr', 'DefaultInvalidImageAlt');
+                $attr['alt'] = $config->get('Attr', 'DefaultInvalidImageAlt');
             }
         }
         
-        return $attributes;
+        return $attr;
         
     }
     

library/HTMLPurifier/ChildDef.php

@@ -21,6 +21,9 @@ HTMLPurifier_ConfigDef::define(
     'preserving child nodes.'
 );
 
+/**
+ * Class that defines allowed child nodes and validates tokens against this.
+ */
 class HTMLPurifier_ChildDef
 {
     var $type;

library/HTMLPurifier/Config.php

@@ -1,6 +1,14 @@
 <?php
 
-// subclass this to add custom settings
+/**
+ * 
+ * 
+ * @note Many classes that could (although many times don't) use the
+ *       configuration object make it a mandatory parameter.  This is
+ *       because a configuration object should always be forwarded,
+ *       otherwise, you run the risk of missing a parameter and then
+ *       being stumped when a configuration directive doesn't work.
+ */
 class HTMLPurifier_Config
 {