Issue #3121155 by quietone, lauriii, bnjmnm, tedbow: Add comments about...

Issue #3121155 by quietone, lauriii, bnjmnm, tedbow: Add comments about alphabetical sorting in UpdateRegistry and test

core/lib/Drupal/Core/Update/UpdateRegistry.php

@@ -91,7 +91,7 @@ public function getRemovedPostUpdates($extension) {
    * Gets all available update functions.
    *
    * @return callable[]
-   *   A list of update functions.
+   *   An alphabetical list of available update functions.
    */
   protected function getAvailableUpdateFunctions() {
     $regexp = '/^(?<extension>.+)_' . $this->updateType . '_(?<name>.+)$/';
@@ -123,7 +123,7 @@ protected function getAvailableUpdateFunctions() {
    * Find all update functions that haven't been executed.
    *
    * @return callable[]
-   *   A list of update functions.
+   *   An alphabetical list of update functions that have not been executed.
    */
   public function getPendingUpdateFunctions() {
     // We need a) the list of active extensions (we get that from the config

core/tests/Drupal/Tests/Core/Update/UpdateRegistryTest.php

@@ -214,6 +214,7 @@ public function testGetPendingUpdateFunctionsNoExistingUpdates() {
         ],
     ], $key_value, $theme_handler, 'post_update');
 
+    // Confirm the updates are sorted alphabetically.
     $this->assertEquals([
       'module_a_post_update_a',
       'module_a_post_update_b',
@@ -251,6 +252,7 @@ public function testGetPendingUpdateFunctionsWithLoadedModulesButNotEnabled() {
         ],
     ], $key_value, $theme_handler, 'post_update');
 
+    // Confirm the updates are sorted alphabetically.
     $this->assertEquals([
       'module_a_post_update_a',
       'module_a_post_update_b',
@@ -295,6 +297,7 @@ public function testGetPendingUpdateFunctionsExistingUpdates() {
         ],
     ], $key_value, $theme_handler, 'post_update');
 
+    // Confirm the updates are sorted alphabetically.
     $this->assertEquals(array_values([
       'module_a_post_update_b',
       'module_b_post_update_a',
@@ -337,6 +340,7 @@ public function testGetPendingUpdateInformation() {
         ],
     ], $key_value, $theme_handler, 'post_update');
 
+    // Confirm the updates are sorted alphabetically.
     $expected = [];
     $expected['module_a']['pending']['a'] = 'Module A update A.';
     $expected['module_a']['pending']['b'] = 'Module A update B.';
@@ -388,6 +392,7 @@ public function testGetPendingUpdateInformationWithExistingUpdates() {
         ],
     ], $key_value, $theme_handler, 'post_update');
 
+    // Confirm the updates are sorted alphabetically.
     $expected = [];
     $expected['module_a']['pending']['b'] = 'Module A update B.';
     $expected['module_a']['start'] = 'b';