Issue #2717541 by msankhala, manish-31, sulfikar_s, Abhijith S, tanubansal,...

Issue #2717541 by msankhala, manish-31, sulfikar_s, Abhijith S, tanubansal, andypost, ashrafabed, alexpott: hook_block_alter documentation missing

(cherry picked from commit e6cba46a)

core/modules/block/block.api.php

@@ -216,6 +216,23 @@ function hook_block_access(\Drupal\block\Entity\Block $block, $operation, \Drupa
   return AccessResult::neutral();
 }
 
+/**
+ * Allow modules to alter the block plugin definitions.
+ *
+ * @param array[] $definitions
+ *   The array of block definitions, keyed by plugin ID.
+ *
+ * @ingroup block_api
+ */
+function hook_block_alter(&$definitions) {
+  foreach ($definitions as $id => $definition) {
+    if (strpos($id, 'system_menu_block:') === 0) {
+      // Replace $definition properties: id, deriver, class, provider to ones
+      // provided by this custom module.
+    }
+  }
+}
+
 /**
  * @} End of "addtogroup hooks".
  */