Convert to PHP 5 only codebase, adding visibility modifiers to all members and methods in the main library area (function only for test methods)

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

configdoc/library/ConfigDoc.php

@@ -4,10 +4,21 @@ require_once 'ConfigDoc/HTMLXSLTProcessor.php';
 require_once 'ConfigDoc/XMLSerializer/Types.php';
 require_once 'ConfigDoc/XMLSerializer/ConfigSchema.php';
 
+/**
+ * Facade class for configuration documentation system
+ */
 class ConfigDoc
 {
     
-    function generate($schema, $xsl_stylesheet_name = 'plain', $parameters = array()) {
+    /**
+     * Generates configuration documentation based on a HTMLPurifier_ConfigSchema
+     * object and styleshet name
+     * @param $schema Instance of HTMLPurifier_ConfigSchema to document
+     * @param $xsl_stylesheet_name Name of XSL stylesheet in ../styles/ directory to use
+     * @param $parameters Extra parameters to pass to the stylesheet
+     * @return string HTML output
+     */
+    public function generate($schema, $xsl_stylesheet_name = 'plain', $parameters = array()) {
         // generate types document, describing type constraints
         $types_serializer = new ConfigDoc_XMLSerializer_Types();
         $types_document = $types_serializer->serialize($schema);
@@ -29,9 +40,10 @@ class ConfigDoc
     
     /**
      * Remove any generated files
+     * @return boolean Success?
      */
-    function cleanup() {
-        unlink('configdoc.xml');
+    public function cleanup() {
+        return unlink('configdoc.xml');
     }
     
 }

configdoc/library/ConfigDoc/HTMLXSLTProcessor.php

@@ -1,12 +1,15 @@
 <?php
 
 /**
- * Special XSLTProcessor specifically for HTML documents. Loosely
- * based off of XSLTProcessor, but not really
+ * Special XSLT processor specifically for HTML documents. Loosely
+ * based off of XSLTProcessor, but does not inherit from that class
  */
 class ConfigDoc_HTMLXSLTProcessor
 {
     
+    /**
+     * Instance of XSLTProcessor
+     */
     protected $xsltProcessor;
     
     public function __construct() {
@@ -16,6 +19,7 @@ class ConfigDoc_HTMLXSLTProcessor
     /**
      * Imports stylesheet for processor to use
      * @param $xsl XSLT DOM tree, or filename of the XSL transformation
+     * @return bool Success?
      */
     public function importStylesheet($xsl) {
         if (is_string($xsl)) {
@@ -27,16 +31,20 @@ class ConfigDoc_HTMLXSLTProcessor
     }
     
     /**
-     * Transforms an XML file into HTML based on the stylesheet
+     * Transforms an XML file into compatible XHTML based on the stylesheet
      * @param $xml XML DOM tree
+     * @return string HTML output
+     * @todo Rename to transformToXHTML, as transformToHTML is misleading
      */
     public function transformToHTML($xml) {
         $out = $this->xsltProcessor->transformToXML($xml);
         
         // fudges for HTML backwards compatibility
+        // assumes that document is XHTML
         $out = str_replace('/>', ' />', $out); // <br /> not <br/>
         $out = str_replace(' xmlns=""', '', $out); // rm unnecessary xmlns
         $out = str_replace(' xmlns="http://www.w3.org/1999/xhtml"', '', $out); // rm unnecessary xmlns
+        
         if (class_exists('Tidy')) {
             // cleanup output
             $config = array(
@@ -49,9 +57,14 @@ class ConfigDoc_HTMLXSLTProcessor
             $tidy->cleanRepair();
             $out = (string) $tidy;
         }
+        
         return $out;
     }
     
+    /**
+     * Bulk sets parameters for the XSL stylesheet
+     * @param array $options Associative array of options to set
+     */
     public function setParameters($options) {
         foreach ($options as $name => $value) {
             $this->xsltProcessor->setParameter('', $name, $value);

configdoc/library/ConfigDoc/XMLSerializer.php

@@ -8,16 +8,22 @@
 class ConfigDoc_XMLSerializer
 {
     
+    /**
+     * Appends a div containing HTML into a node
+     * @param $document Base document node belongs to
+     * @param $node Node to append to
+     * @param $html HTML to place inside div to append
+     * @todo Place this directly in DOMNode, using registerNodeClass to
+     *       override.
+     */
     protected function appendHTMLDiv($document, $node, $html) {
         $purifier = HTMLPurifier::getInstance();
         $html = $purifier->purify($html);
         $dom_html = $document->createDocumentFragment();
         $dom_html->appendXML($html);
-        
         $dom_div = $document->createElement('div');
         $dom_div->setAttribute('xmlns', 'http://www.w3.org/1999/xhtml');
         $dom_div->appendChild($dom_html);
-        
         $node->appendChild($dom_div);
     }
     

configdoc/library/ConfigDoc/XMLSerializer/ConfigSchema.php

@@ -9,6 +9,7 @@ class ConfigDoc_XMLSerializer_ConfigSchema extends ConfigDoc_XMLSerializer
      * Serializes a schema into DOM form
      * @todo Split into sub-serializers
      * @param $schema HTMLPurifier_ConfigSchema to serialize
+     * @return DOMDocument representation of schema
      */
     public function serialize($schema) {
         $dom_document = new DOMDocument('1.0', 'UTF-8');

configdoc/library/ConfigDoc/XMLSerializer/Types.php

@@ -8,6 +8,7 @@ class ConfigDoc_XMLSerializer_Types extends ConfigDoc_XMLSerializer
     /**
      * Serializes the types in a schema into DOM form
      * @param $schema HTMLPurifier_ConfigSchema owner of types to serialize
+     * @return DOMDocument representing schema types
      */
     public function serialize($schema) {
         $types_document = new DOMDocument('1.0', 'UTF-8');