From db33512d7ec1564174b827f87e9216cc751a646b Mon Sep 17 00:00:00 2001
From: Tim Starling <tstarling@users.mediawiki.org>
Date: Mon, 18 Feb 2008 07:45:44 +0000
Subject: [PATCH] Documentation.

---
 includes/Preprocessor.php      | 78 +++++++++++++++++++++++++++++++++-
 includes/Preprocessor_DOM.php  |  6 ++-
 includes/Preprocessor_Hash.php |  8 ++--
 3 files changed, 85 insertions(+), 7 deletions(-)

diff --git a/includes/Preprocessor.php b/includes/Preprocessor.php
index 2543a23dc8..34bc1e5b3a 100644
--- 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 c3ed83aa2a..0e2e9a1615 100644
--- 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 1d6331bd0d..2034278d4b 100644
--- 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' ) {
-- 
2.20.1