Comment on each step of the minification process

Author: blmage

lib/internal/Magento/Framework/View/Template/Html/Minifier.php

@@ -119,11 +119,12 @@ public function minify($file)
         $content = $this->readFactory->create($dir)->readFile($fileName);
         $heredocs = null;
 
+        // Safely minify PHP code and remove single-line PHP comments by using a parser.
         if (null !== $content) {
             $parser = (new \PhpParser\ParserFactory())->create(\PhpParser\ParserFactory::PREFER_PHP7);
 
             /**
-             * Prevent problems with deeply nested ASTs if xDebug is enabled.
+             * Prevent problems with deeply nested ASTs if Xdebug is enabled.
              * @see https://github.com/nikic/PHP-Parser/blob/v4.4.0/doc/2_Usage_of_basic_components.markdown#bootstrapping
              */
             $nestingLevelConfigValue = ini_get('xdebug.max_nesting_level');
@@ -151,7 +152,7 @@ public function minify($file)
             }
         }
 
-        //Storing Heredocs
+        // Stash the heredocs now if the template could not be parsed.
         if (null === $heredocs) {
             $content = preg_replace_callback(
                 '/<<<([A-z]+).*?\1\s*;/ims',
@@ -164,23 +165,33 @@ function ($match) use (&$heredocs) {
             );
         }
 
+        // Remove insignificant spaces before closing HTML tags
+        // (preserve one space after ]]>, and all spaces inside <pre> and <textarea> tags).
         $content = preg_replace(
             '#(?<!]]>)\s+</(?!(?>textarea|pre)\b)#',
             '</',
+            // Remove redundant spaces after PHP tags that do not start with a print or condition statement,
+            // and that do not contain any "?".
             preg_replace(
                 '#((?:<\?php\s+(?!echo|print|if|elseif|else)[^\?]*)\?>)\s+#',
                 '$1 ',
+                // Remove single space in empty non-inline tags.
                 preg_replace(
                     '#(?<!' . implode('|', $this->inlineHtmlTags) . ')\> \<#',
                     '><',
+                    // Remove redundant spaces outside of tags in which they are relevant.
                     preg_replace(
                         '#(?ix)(?>[^\S ]\s*|\s{2,})(?=(?:(?:[^<]++|<(?!/?(?:textarea|pre|script)\b))*+)'
                         . '(?:<(?>textarea|pre|script)\b|\z))#',
                         ' ',
+                        // Remove single-line comments in <script> tags, except for <![CDATA[ and ]]>.
+                        // Do nothing if the "//" part is seemingly part of a string / URL / RegExp.
                         preg_replace(
                             '#(?<!:|\\\\|\\\|\'|"|/)//(?!/)(?!\s*\<\!\[)(?!\s*]]\>)[^\n\r]*'
                             . '(?!(?:(?:[^<]++|<(?!/?(?:script)\b))*+)(?:<(?>script)\b|\z))#',
                             '',
+                            // Remove commented single-line PHP tags in <script> tags.
+                            // Do nothing if the "//" part is seemingly part of a URL / RegExp.
                             preg_replace(
                                 '#(?<!:|\\\)//[^\n\r]*(\<\?(php|=))[^\n\r]*(\s\?\>)[^\n\r]*'
                                 . '(?!(?:(?:[^<]++|<(?!/?(?:script)\b))*+)(?:<(?>script)\b|\z))#',
@@ -193,7 +204,7 @@ function ($match) use (&$heredocs) {
             )
         );
 
-        //Restoring Heredocs
+        // Restore the stashed heredocs.
         $content = preg_replace_callback(
             '/__MINIFIED_HEREDOC__(\d+)/ims',
             function ($match) use ($heredocs) {