Add lots of documentation.

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

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);
     }
 }