Make WordPress Core


Ignore:
Timestamp:
01/29/2020 12:43:23 AM (7 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/shortcodes.php

    r47087 r47122  
    218218        $content = preg_replace_callback( "/$pattern/", 'do_shortcode_tag', $content );
    219219
    220         // Always restore square braces so we don't break things like <!--[if IE ]>
     220        // Always restore square braces so we don't break things like <!--[if IE ]>.
    221221        $content = unescape_invalid_shortcodes( $content );
    222222
     
    255255        $tagregexp = join( '|', array_map( 'preg_quote', $tagnames ) );
    256256
    257         // WARNING! Do not change this regex without changing do_shortcode_tag() and strip_shortcode_tag()
     257        // WARNING! Do not change this regex without changing do_shortcode_tag() and strip_shortcode_tag().
    258258        // Also, see shortcode_unautop() and shortcode.js.
    259259
    260260        // phpcs:disable Squiz.Strings.ConcatenationSpacing.PaddingFound -- don't remove regex indentation
    261261        return
    262                 '\\['                                // Opening bracket
    263                 . '(\\[?)'                           // 1: Optional second opening bracket for escaping shortcodes: [[tag]]
    264                 . "($tagregexp)"                     // 2: Shortcode name
    265                 . '(?![\\w-])'                       // Not followed by word character or hyphen
    266                 . '('                                // 3: Unroll the loop: Inside the opening shortcode tag
    267                 .     '[^\\]\\/]*'                   // Not a closing bracket or forward slash
     262                '\\['                                // Opening bracket.
     263                . '(\\[?)'                           // 1: Optional second opening bracket for escaping shortcodes: [[tag]].
     264                . "($tagregexp)"                     // 2: Shortcode name.
     265                . '(?![\\w-])'                       // Not followed by word character or hyphen.
     266                . '('                                // 3: Unroll the loop: Inside the opening shortcode tag.
     267                .     '[^\\]\\/]*'                   // Not a closing bracket or forward slash.
    268268                .     '(?:'
    269                 .         '\\/(?!\\])'               // A forward slash not followed by a closing bracket
    270                 .         '[^\\]\\/]*'               // Not a closing bracket or forward slash
     269                .         '\\/(?!\\])'               // A forward slash not followed by a closing bracket.
     270                .         '[^\\]\\/]*'               // Not a closing bracket or forward slash.
    271271                .     ')*?'
    272272                . ')'
    273273                . '(?:'
    274                 .     '(\\/)'                        // 4: Self closing tag ...
    275                 .     '\\]'                          // ... and closing bracket
     274                .     '(\\/)'                        // 4: Self closing tag...
     275                .     '\\]'                          // ...and closing bracket.
    276276                . '|'
    277                 .     '\\]'                          // Closing bracket
     277                .     '\\]'                          // Closing bracket.
    278278                .     '(?:'
    279                 .         '('                        // 5: Unroll the loop: Optionally, anything between the opening and closing shortcode tags
    280                 .             '[^\\[]*+'             // Not an opening bracket
     279                .         '('                        // 5: Unroll the loop: Optionally, anything between the opening and closing shortcode tags.
     280                .             '[^\\[]*+'             // Not an opening bracket.
    281281                .             '(?:'
    282                 .                 '\\[(?!\\/\\2\\])' // An opening bracket not followed by the closing shortcode tag
    283                 .                 '[^\\[]*+'         // Not an opening bracket
     282                .                 '\\[(?!\\/\\2\\])' // An opening bracket not followed by the closing shortcode tag.
     283                .                 '[^\\[]*+'         // Not an opening bracket.
    284284                .             ')*+'
    285285                .         ')'
    286                 .         '\\[\\/\\2\\]'             // Closing shortcode tag
     286                .         '\\[\\/\\2\\]'             // Closing shortcode tag.
    287287                .     ')?'
    288288                . ')'
    289                 . '(\\]?)';                          // 6: Optional second closing brocket for escaping shortcodes: [[tag]]
     289                . '(\\]?)';                          // 6: Optional second closing brocket for escaping shortcodes: [[tag]].
    290290        // phpcs:enable
    291291}
     
    307307        global $shortcode_tags;
    308308
    309         // allow [[foo]] syntax for escaping a tag
     309        // Allow [[foo]] syntax for escaping a tag.
    310310        if ( $m[1] == '[' && $m[6] == ']' ) {
    311311                return substr( $m[0], 1, -1 );
     
    397397                        // This element does not contain shortcodes.
    398398                        if ( $noopen xor $noclose ) {
    399                                 // Need to encode stray [ or ] chars.
     399                                // Need to encode stray '[' or ']' chars.
    400400                                $element = strtr( $element, $trans );
    401401                        }
     
    404404
    405405                if ( $ignore_html || '<!--' === substr( $element, 0, 4 ) || '<![CDATA[' === substr( $element, 0, 9 ) ) {
    406                         // Encode all [ and ] chars.
     406                        // Encode all '[' and ']' chars.
    407407                        $element = strtr( $element, $trans );
    408408                        continue;
     
    416416                        }
    417417
    418                         // Looks like we found some crazy unfiltered HTML.  Skipping it for sanity.
     418                        // Looks like we found some crazy unfiltered HTML. Skipping it for sanity.
    419419                        $element = strtr( $element, $trans );
    420420                        continue;
    421421                }
    422422
    423                 // Get element name
     423                // Get element name.
    424424                $front   = array_shift( $attributes );
    425425                $back    = array_pop( $attributes );
     
    433433                        $close = strpos( $attr, ']' );
    434434                        if ( false === $open || false === $close ) {
    435                                 continue; // Go to next attribute.  Square braces will be escaped at end of loop.
     435                                continue; // Go to next attribute. Square braces will be escaped at end of loop.
    436436                        }
    437437                        $double = strpos( $attr, '"' );
    438438                        $single = strpos( $attr, "'" );
    439439                        if ( ( false === $single || $open < $single ) && ( false === $double || $open < $double ) ) {
    440                                 // $attr like '[shortcode]' or 'name = [shortcode]' implies unfiltered_html.
    441                                 // In this specific situation we assume KSES did not run because the input
    442                                 // was written by an administrator, so we should avoid changing the output
    443                                 // and we do not need to run KSES here.
     440                                /*
     441                                 * $attr like '[shortcode]' or 'name = [shortcode]' implies unfiltered_html.
     442                                 * In this specific situation we assume KSES did not run because the input
     443                                 * was written by an administrator, so we should avoid changing the output
     444                                 * and we do not need to run KSES here.
     445                                 */
    444446                                $attr = preg_replace_callback( "/$pattern/", 'do_shortcode_tag', $attr );
    445447                        } else {
    446                                 // $attr like 'name = "[shortcode]"' or "name = '[shortcode]'"
     448                                // $attr like 'name = "[shortcode]"' or "name = '[shortcode]'".
    447449                                // We do not know if $content was unfiltered. Assume KSES ran before shortcodes.
    448450                                $count    = 0;
     
    460462                $element = $front . implode( '', $attributes ) . $back;
    461463
    462                 // Now encode any remaining [ or ] chars.
     464                // Now encode any remaining '[' or ']' chars.
    463465                $element = strtr( $element, $trans );
    464466        }
     
    647649        $content = preg_replace_callback( "/$pattern/", 'strip_shortcode_tag', $content );
    648650
    649         // Always restore square braces so we don't break things like <!--[if IE ]>
     651        // Always restore square braces so we don't break things like <!--[if IE ]>.
    650652        $content = unescape_invalid_shortcodes( $content );
    651653
     
    662664 */
    663665function strip_shortcode_tag( $m ) {
    664         // allow [[foo]] syntax for escaping a tag
     666        // Allow [[foo]] syntax for escaping a tag.
    665667        if ( $m[1] == '[' && $m[6] == ']' ) {
    666668                return substr( $m[0], 1, -1 );
Note: See TracChangeset for help on using the changeset viewer.