From b92bab01f0e0688b66616747adab2c3de8da7433 Mon Sep 17 00:00:00 2001
From: Kunal Mehta <legoktm@member.fsf.org>
Date: Tue, 11 Oct 2016 11:27:06 -0700
Subject: [PATCH] Balancer: Add a bunch of phpdoc and 2 fixmes

Change-Id: I0596c73cc87ec609d75aa4d8b241c2377bc4f9b1
---
 includes/tidy/Balancer.php | 31 +++++++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/includes/tidy/Balancer.php b/includes/tidy/Balancer.php
index 069b460fd8..aef73c7258 100644
--- a/includes/tidy/Balancer.php
+++ b/includes/tidy/Balancer.php
@@ -328,7 +328,7 @@ class BalanceElement {
 	/**
 	 * Parent of this element, or the string "flat" if this element has
 	 * already been flattened into its parent.
-	 * @var string|null $parent
+	 * @var BalanceElement|string|null $parent
 	 */
 	public $parent;
 
@@ -337,7 +337,7 @@ class BalanceElement {
 	 * child will be an actual BalanceElement object; the rest will
 	 * be strings, representing either text nodes or flattened
 	 * BalanceElement objects.
-	 * @var array $children
+	 * @var BalanceElement[]|string[] $children
 	 */
 	public $children;
 
@@ -465,6 +465,7 @@ class BalanceElement {
 	 * in its parent by that string.
 	 *
 	 * @param array $config Balancer configuration; see Balancer::__construct().
+	 * @return string
 	 *
 	 * @see __toString()
 	 */
@@ -653,7 +654,7 @@ class BalanceElement {
 class BalanceStack implements IteratorAggregate {
 	/**
 	 * Backing storage for the stack.
-	 * @var array $elements
+	 * @var BalanceElement[] $elements
 	 */
 	private $elements = [];
 	/**
@@ -717,6 +718,7 @@ class BalanceStack implements IteratorAggregate {
 	/**
 	 * Insert text at the appropriate place for inserting a node.
 	 * @param string $value
+	 * @param bool $isComment
 	 * @see https://html.spec.whatwg.org/multipage/syntax.html#appropriate-place-for-inserting-a-node
 	 */
 	public function insertText( $value, $isComment = false ) {
@@ -906,7 +908,7 @@ class BalanceStack implements IteratorAggregate {
 	/**
 	 * Return an iterator over this stack which visits the current node
 	 * first, and the root node last.
-	 * @return Iterator
+	 * @return \Iterator
 	 */
 	public function getIterator() {
 		return new ReverseArrayIterator( $this->elements );
@@ -1080,6 +1082,8 @@ class BalanceStack implements IteratorAggregate {
 	/**
 	 * Foster parent the given $elt in the stack of open elements.
 	 * @param BalanceElement|string $elt
+	 * @return BalanceElement|string
+	 *
 	 * @see https://html.spec.whatwg.org/multipage/syntax.html#foster-parent
 	 */
 	private function fosterParent( $elt ) {
@@ -1520,6 +1524,7 @@ class BalanceActiveFormattingElements {
 
 	/**
 	 * Determine whether an element is in the list of formatting elements.
+	 * @param BalanceElement $elt
 	 * @return boolean
 	 */
 	public function isInList( BalanceElement $elt ) {
@@ -1529,6 +1534,8 @@ class BalanceActiveFormattingElements {
 	/**
 	 * Find the element $elt in the list and remove it.
 	 * Used when parsing &lt;a&gt; in body mode.
+	 *
+	 * @param BalanceElement $elt
 	 */
 	public function remove( BalanceElement $elt ) {
 		if ( $this->head !== $elt && !$elt->prevAFE ) {
@@ -1597,6 +1604,9 @@ class BalanceActiveFormattingElements {
 
 	/**
 	 * Find element $a in the list and replace it with element $b
+	 *
+	 * @param BalanceElement $a
+	 * @param BalanceElement $b
 	 */
 	public function replace( BalanceElement $a, BalanceElement $b ) {
 		if ( $this->head !== $a && !$a->prevAFE ) {
@@ -1628,6 +1638,9 @@ class BalanceActiveFormattingElements {
 
 	/**
 	 * Find $a in the list and insert $b after it.
+
+	 * @param BalanceElement $a
+	 * @param BalanceElement $b
 	 */
 	public function insertAfter( BalanceElement $a, BalanceElement $b ) {
 		if ( $this->head !== $a && !$a->prevAFE ) {
@@ -1778,9 +1791,12 @@ class BalanceActiveFormattingElements {
  */
 class Balancer {
 	private $parseMode;
+	/** @var \Iterator */
 	private $bitsIterator;
 	private $allowedHtmlElements;
+	/** @var BalanceActiveFormattingElements */
 	private $afe;
+	/** @var BalanceStack */
 	private $stack;
 	private $strict;
 	private $allowComments;
@@ -1795,6 +1811,11 @@ class Balancer {
 	private $inRCDATA;
 	private $inRAWTEXT;
 
+	/** @var callable|null */
+	private $processingCallback;
+	/** @var array */
+	private $processingArgs;
+
 	/**
 	 * Valid HTML5 comments.
 	 * Regex borrowed from Tim Starling's "remex-html" project.
@@ -2582,6 +2603,7 @@ class Balancer {
 			case 'tt':
 			case 'u':
 				$this->afe->reconstruct( $this->stack );
+				// FIXME: only takes one parameter
 				$this->afe->push( $this->stack->insertHTMLElement( $value, $attribs ), $attribs );
 				return true;
 
@@ -2591,6 +2613,7 @@ class Balancer {
 					$this->inBodyMode( 'endtag', 'nobr' );
 					$this->afe->reconstruct( $this->stack );
 				}
+				// FIXME: only takes one parameter
 				$this->afe->push( $this->stack->insertHTMLElement( $value, $attribs ), $attribs );
 				return true;
 
-- 
2.20.1