From 046d986b1674d15172942dbbc7cfa1b7303035e6 Mon Sep 17 00:00:00 2001
From: Andrew Garrett <werdna@users.mediawiki.org>
Date: Thu, 18 Jun 2009 20:51:48 +0000
Subject: [PATCH] Documentation I added while trying to figure out
 doBlockLevels, might be useful to others

---
 includes/parser/Parser.php | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php
index a5e721db31..0649cd7ba7 100644
--- a/includes/parser/Parser.php
+++ b/includes/parser/Parser.php
@@ -1934,9 +1934,9 @@ class Parser
 		$result = $this->closeParagraph();
 
 		if ( '*' === $char ) { $result .= '<ul><li>'; }
-		else if ( '#' === $char ) { $result .= '<ol><li>'; }
-		else if ( ':' === $char ) { $result .= '<dl><dd>'; }
-		else if ( ';' === $char ) {
+		elseif ( '#' === $char ) { $result .= '<ol><li>'; }
+		elseif ( ':' === $char ) { $result .= '<dl><dd>'; }
+		elseif ( ';' === $char ) {
 			$result .= '<dl><dt>';
 			$this->mDTopen = true;
 		}
@@ -1947,7 +1947,7 @@ class Parser
 
 	/* private */ function nextItem( $char ) {
 		if ( '*' === $char || '#' === $char ) { return '</li><li>'; }
-		else if ( ':' === $char || ';' === $char ) {
+		elseif ( ':' === $char || ';' === $char ) {
 			$close = '</dd>';
 			if ( $this->mDTopen ) { $close = '</dt>'; }
 			if ( ';' === $char ) {
@@ -1963,8 +1963,8 @@ class Parser
 
 	/* private */ function closeList( $char ) {
 		if ( '*' === $char ) { $text = '</li></ul>'; }
-		else if ( '#' === $char ) { $text = '</li></ol>'; }
-		else if ( ':' === $char ) {
+		elseif ( '#' === $char ) { $text = '</li></ol>'; }
+		elseif ( ':' === $char ) {
 			if ( $this->mDTopen ) {
 				$this->mDTopen = false;
 				$text = '</dt></dl>';
@@ -1980,6 +1980,7 @@ class Parser
 	/**
 	 * Make lists from lines starting with ':', '*', '#', etc. (DBL)
 	 *
+	 * @param $linestart bool whether or not this is at the start of a line.
 	 * @private
 	 * @return string the lists rendered as HTML
 	 */
@@ -2004,16 +2005,24 @@ class Parser
 				$linestart = true;
 				continue;
 			}
+			// * = ul
+			// # = ol
+			// ; = dt
+			// : = dd
 
 			$lastPrefixLength = strlen( $lastPrefix );
 			$preCloseMatch = preg_match('/<\\/pre/i', $oLine );
 			$preOpenMatch = preg_match('/<pre/i', $oLine );
+			// If not in a <pre> element, scan for and figure out what prefixes are there.
 			if ( !$this->mInPre ) {
 				# Multiple prefixes may abut each other for nested lists.
 				$prefixLength = strspn( $oLine, '*#:;' );
 				$prefix = substr( $oLine, 0, $prefixLength );
 
 				# eh?
+				// ; and : are both from definition-lists, so they're equivalent
+				//  for the purposes of determining whether or not we need to open/close
+				//  elements.
 				$prefix2 = str_replace( ';', ':', $prefix );
 				$t = substr( $oLine, $prefixLength );
 				$this->mInPre = (bool)$preOpenMatch;
@@ -2042,17 +2051,24 @@ class Parser
 					}
 				}
 			} elseif( $prefixLength || $lastPrefixLength ) {
+				// We need to open or close prefixes, or both.
+				
 				# Either open or close a level...
 				$commonPrefixLength = $this->getCommon( $prefix, $lastPrefix );
 				$paragraphStack = false;
 
+				// Close all the prefixes which aren't shared.
 				while( $commonPrefixLength < $lastPrefixLength ) {
 					$output .= $this->closeList( $lastPrefix[$lastPrefixLength-1] );
 					--$lastPrefixLength;
 				}
+				
+				// Continue the current prefix if appropriate.
 				if ( $prefixLength <= $commonPrefixLength && $commonPrefixLength > 0 ) {
 					$output .= $this->nextItem( $prefix[$commonPrefixLength-1] );
 				}
+				
+				// Open prefixes where appropriate.
 				while ( $prefixLength > $commonPrefixLength ) {
 					$char = substr( $prefix, $commonPrefixLength, 1 );
 					$output .= $this->openList( $char );
@@ -2068,6 +2084,8 @@ class Parser
 				}
 				$lastPrefix = $prefix2;
 			}
+			
+			// If we have no prefixes, go to paragraph mode.
 			if( 0 == $prefixLength ) {
 				wfProfileIn( __METHOD__."-paragraph" );
 				# No prefix (not in list)--go to paragraph mode
-- 
2.20.1