Documentation.

diff --git a/includes/Preprocessor.php b/includes/Preprocessor.php
index 2543a23..34bc1e5 100644 (file)
--- a/includes/Preprocessor.php
+++ b/includes/Preprocessor.php
@@ -1,8 +1,13 @@
 <?php
 
 interface Preprocessor {
+       /** Create a new preprocessor object based on an initialised Parser object */
        function __construct( $parser );
+
+       /** Create a new top-level frame for expansion of a page */
        function newFrame();
+
+       /** Preprocess text to a PPNode */
        function preprocessToObj( $text, $flags = 0 );
 }
 
@@ -50,7 +55,10 @@ interface PPFrame {
         * Returns true if there are no arguments in this frame
         */
        function isEmpty();
-       
+
+       /**
+        * Get an argument to this frame by name 
+        */
        function getArgument( $name );
 
        /**
@@ -64,17 +72,83 @@ interface PPFrame {
        function isTemplate();
 }
 
+/**
+ * There are three types of nodes:
+ *     * Tree nodes, which have a name and contain other nodes as children
+ *     * Array nodes, which also contain other nodes but aren't considered part of a tree
+ *     * Leaf nodes, which contain the actual data
+ *
+ * This interface provides access to the tree structure and to the contents of array nodes,
+ * but it does not provide access to the internal structure of leaf nodes. Access to leaf 
+ * data is provided via two means:
+ *     * PPFrame::expand(), which provides expanded text
+ *     * The PPNode::split*() functions, which provide metadata about certain types of tree node
+ */
 interface PPNode {
+       /** 
+        * Get an array-type node containing the children of this node.
+        * Returns false if this is not a tree node.
+        */
        function getChildren();
+
+       /**
+        * Get the first child of a tree node. False if there isn't one.
+        */
        function getFirstChild();
+
+       /**
+        * Get the next sibling of any node. False if there isn't one
+        */
        function getNextSibling();
+
+       /**
+        * Get all children of this tree node which have a given name.
+        * Returns an array-type node, or false if this is not a tree node.
+        */
        function getChildrenOfType( $type );
+
+
+       /**
+        * Returns the length of the array, or false if this is not an array-type node
+        */
        function getLength();
+
+       /**
+        * Returns an item of an array-type node
+        */
        function item( $i );
+
+       /**     
+        * Get the name of this node. The following names are defined here:
+        *
+        *    h             A heading node.
+        *    template      A double-brace node.
+        *    tplarg        A triple-brace node.
+        *    title         The first argument to a template or tplarg node.
+        *    part          Subsequent arguments to a template or tplarg node.
+        *    #nodelist     An array-type node
+        *
+        * The subclass may define various other names for tree and leaf nodes.
+        */
        function getName();
-       
+
+       /**
+        * Split a <part> node into an associative array containing:
+        *    name          PPNode name
+        *    index         String index
+        *    value         PPNode value 
+        */
        function splitArg();
+
+       /**
+        * Split an <ext> node into an associative array containing name, attr, inner and close
+        * All values in the resulting array are PPNodes. Inner and close are optional.
+        */
        function splitExt();
+
+       /**
+        * Split an <h> node
+        */
        function splitHeading();
 }
 

diff --git a/includes/Preprocessor_DOM.php b/includes/Preprocessor_DOM.php
index c3ed83a..0e2e9a1 100644 (file)
--- a/includes/Preprocessor_DOM.php
+++ b/includes/Preprocessor_DOM.php
@@ -1297,8 +1297,10 @@ class PPNode_DOM implements PPNode {
        }
 
        /**
-        * Split an <arg> node into a three-element array: 
-        *    PPNode name, string index and PPNode value
+        * Split a <part> node into an associative array containing:
+        *    name          PPNode name
+        *    index         String index
+        *    value         PPNode value 
         */
        function splitArg() {
                $names = $this->xpath->query( 'name', $this->node );

diff --git a/includes/Preprocessor_Hash.php b/includes/Preprocessor_Hash.php
index 1d6331b..2034278 100644 (file)
--- a/includes/Preprocessor_Hash.php
+++ b/includes/Preprocessor_Hash.php
@@ -1265,8 +1265,10 @@ class PPNode_Hash_Tree implements PPNode {
        }
 
        /**
-        * Split an <arg> node into a three-element array: 
-        *    PPNode name, string index and PPNode value
+        * Split a <part> node into an associative array containing:
+        *    name          PPNode name
+        *    index         String index
+        *    value         PPNode value 
         */
        function splitArg() {
                $bits = array();
@@ -1322,7 +1324,7 @@ class PPNode_Hash_Tree implements PPNode {
        }
 
        /**
-        * Split a <h> node
+        * Split an <h> node
         */
        function splitHeading() {
                if ( $this->name !== 'h' ) {