Changeset 47122 for trunk/src/wp-includes/shortcodes.php

Timestamp:

01/29/2020 12:43:23 AM (6 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:

• trunk/src/wp-includes/shortcodes.php (modified) (10 diffs)

trunk/src/wp-includes/shortcodes.php

@@ -218 +218 @@
     $content = preg_replace_callback( "/$pattern/", 'do_shortcode_tag', $content );
 
-    // Always restore square braces so we don't break things like <!--[if IE ]>
+    // Always restore square braces so we don't break things like <!--[if IE ]>.
     $content = unescape_invalid_shortcodes( $content );
 
@@ -255 +255 @@
     $tagregexp = join( '|', array_map( 'preg_quote', $tagnames ) );
 
-    // WARNING! Do not change this regex without changing do_shortcode_tag() and strip_shortcode_tag()
+    // WARNING! Do not change this regex without changing do_shortcode_tag() and strip_shortcode_tag().
     // Also, see shortcode_unautop() and shortcode.js.
 
     // phpcs:disable Squiz.Strings.ConcatenationSpacing.PaddingFound -- don't remove regex indentation
     return
-        '\\['                                // Opening bracket
-        . '(\\[?)'                           // 1: Optional second opening bracket for escaping shortcodes: [[tag]]
-        . "($tagregexp)"                     // 2: Shortcode name
-        . '(?![\\w-])'                       // Not followed by word character or hyphen
-        . '('                                // 3: Unroll the loop: Inside the opening shortcode tag
-        .     '[^\\]\\/]*'                   // Not a closing bracket or forward slash
+        '\\['                                // Opening bracket.
+        . '(\\[?)'                           // 1: Optional second opening bracket for escaping shortcodes: [[tag]].
+        . "($tagregexp)"                     // 2: Shortcode name.
+        . '(?![\\w-])'                       // Not followed by word character or hyphen.
+        . '('                                // 3: Unroll the loop: Inside the opening shortcode tag.
+        .     '[^\\]\\/]*'                   // Not a closing bracket or forward slash.
         .     '(?:'
-        .         '\\/(?!\\])'               // A forward slash not followed by a closing bracket
-        .         '[^\\]\\/]*'               // Not a closing bracket or forward slash
+        .         '\\/(?!\\])'               // A forward slash not followed by a closing bracket.
+        .         '[^\\]\\/]*'               // Not a closing bracket or forward slash.
         .     ')*?'
         . ')'
         . '(?:'
-        .     '(\\/)'                        // 4: Self closing tag ...
-        .     '\\]'                          // ... and closing bracket
+        .     '(\\/)'                        // 4: Self closing tag...
+        .     '\\]'                          // ...and closing bracket.
         . '|'
-        .     '\\]'                          // Closing bracket
+        .     '\\]'                          // Closing bracket.
         .     '(?:'
-        .         '('                        // 5: Unroll the loop: Optionally, anything between the opening and closing shortcode tags
-        .             '[^\\[]*+'             // Not an opening bracket
+        .         '('                        // 5: Unroll the loop: Optionally, anything between the opening and closing shortcode tags.
+        .             '[^\\[]*+'             // Not an opening bracket.
         .             '(?:'
-        .                 '\\[(?!\\/\\2\\])' // An opening bracket not followed by the closing shortcode tag
-        .                 '[^\\[]*+'         // Not an opening bracket
+        .                 '\\[(?!\\/\\2\\])' // An opening bracket not followed by the closing shortcode tag.
+        .                 '[^\\[]*+'         // Not an opening bracket.
         .             ')*+'
         .         ')'
-        .         '\\[\\/\\2\\]'             // Closing shortcode tag
+        .         '\\[\\/\\2\\]'             // Closing shortcode tag.
         .     ')?'
         . ')'
-        . '(\\]?)';                          // 6: Optional second closing brocket for escaping shortcodes: [[tag]]
+        . '(\\]?)';                          // 6: Optional second closing brocket for escaping shortcodes: [[tag]].
     // phpcs:enable
 }
@@ -307 +307 @@
     global $shortcode_tags;
 
-    // allow [[foo]] syntax for escaping a tag
+    // Allow [[foo]] syntax for escaping a tag.
     if ( $m[1] == '[' && $m[6] == ']' ) {
         return substr( $m[0], 1, -1 );
@@ -397 +397 @@
             // This element does not contain shortcodes.
             if ( $noopen xor $noclose ) {
-                // Need to encode stray [ or ] chars.
+                // Need to encode stray '[' or ']' chars.
                 $element = strtr( $element, $trans );
             }
@@ -404 +404 @@
 
         if ( $ignore_html || '<!--' === substr( $element, 0, 4 ) || '<![CDATA[' === substr( $element, 0, 9 ) ) {
-            // Encode all [ and ] chars.
+            // Encode all '[' and ']' chars.
             $element = strtr( $element, $trans );
             continue;
@@ -416 +416 @@
             }
 
-            // Looks like we found some crazy unfiltered HTML.  Skipping it for sanity.
+            // Looks like we found some crazy unfiltered HTML. Skipping it for sanity.
             $element = strtr( $element, $trans );
             continue;
         }
 
-        // Get element name
+        // Get element name.
         $front   = array_shift( $attributes );
         $back    = array_pop( $attributes );
@@ -433 +433 @@
             $close = strpos( $attr, ']' );
             if ( false === $open || false === $close ) {
-                continue; // Go to next attribute.  Square braces will be escaped at end of loop.
+                continue; // Go to next attribute. Square braces will be escaped at end of loop.
             }
             $double = strpos( $attr, '"' );
             $single = strpos( $attr, "'" );
             if ( ( false === $single || $open < $single ) && ( false === $double || $open < $double ) ) {
-                // $attr like '[shortcode]' or 'name = [shortcode]' implies unfiltered_html.
-                // In this specific situation we assume KSES did not run because the input
-                // was written by an administrator, so we should avoid changing the output
-                // and we do not need to run KSES here.
+                /*
+                 * $attr like '[shortcode]' or 'name = [shortcode]' implies unfiltered_html.
+                 * In this specific situation we assume KSES did not run because the input
+                 * was written by an administrator, so we should avoid changing the output
+                 * and we do not need to run KSES here.
+                 */
                 $attr = preg_replace_callback( "/$pattern/", 'do_shortcode_tag', $attr );
             } else {
-                // $attr like 'name = "[shortcode]"' or "name = '[shortcode]'"
+                // $attr like 'name = "[shortcode]"' or "name = '[shortcode]'".
                 // We do not know if $content was unfiltered. Assume KSES ran before shortcodes.
                 $count    = 0;
@@ -460 +462 @@
         $element = $front . implode( '', $attributes ) . $back;
 
-        // Now encode any remaining [ or ] chars.
+        // Now encode any remaining '[' or ']' chars.
         $element = strtr( $element, $trans );
     }
@@ -647 +649 @@
     $content = preg_replace_callback( "/$pattern/", 'strip_shortcode_tag', $content );
 
-    // Always restore square braces so we don't break things like <!--[if IE ]>
+    // Always restore square braces so we don't break things like <!--[if IE ]>.
     $content = unescape_invalid_shortcodes( $content );
 
@@ -662 +664 @@
  */
 function strip_shortcode_tag( $m ) {
-    // allow [[foo]] syntax for escaping a tag
+    // Allow [[foo]] syntax for escaping a tag.
     if ( $m[1] == '[' && $m[6] == ']' ) {
         return substr( $m[0], 1, -1 );