Documentation I added while trying to figure out doBlockLevels, might be useful to...

diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php
index a5e721d..0649cd7 100644 (file)
--- 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