diff --git a/core/lib/Drupal/Core/Extension/ModuleUninstallValidatorInterface.php b/core/lib/Drupal/Core/Extension/ModuleUninstallValidatorInterface.php
index 8eb5906..96c1ca5 100644
--- a/core/lib/Drupal/Core/Extension/ModuleUninstallValidatorInterface.php
+++ b/core/lib/Drupal/Core/Extension/ModuleUninstallValidatorInterface.php
@@ -14,6 +14,13 @@
 
   /**
    * Determines the reasons a module can not be uninstalled.
+   * For example: can be used to replace $info['required'] to see if a module can
+   * be deleted.
+   *
+   * @code
+   * if ($module == 'example') {
+   *  $reasons[] = $this->t('Can never be uninstalled.');
+   * }
    *
    * @param string $module
    *   A module name.
diff --git a/core/lib/Drupal/Core/Extension/module.api.php b/core/lib/Drupal/Core/Extension/module.api.php
index d7d5332..871c954 100644
--- a/core/lib/Drupal/Core/Extension/module.api.php
+++ b/core/lib/Drupal/Core/Extension/module.api.php
@@ -131,13 +131,19 @@ function hook_module_implements_alter(&$implementations, $hook) {
 }
 
 /**
- * Alter the information parsed from module and theme .info.yml files
+ * Alter the information parsed from module and theme .info.yml files.
  *
  * This hook is invoked in _system_rebuild_module_data() and in
  * \Drupal\Core\Extension\ThemeHandlerInterface::rebuildThemeData(). A module
  * may implement this hook in order to add to or alter the data generated by
  * reading the .info.yml file with \Drupal\Core\Extension\InfoParser.
  *
+ * Note that it is preferable for performance reasons to use
+ * \Drupal\Core\Extension\ModuleUninstallValidatorInterface to mark a module as
+ * required. Setting the $info['required'] key in implementations of this hook
+ * is discouraged. See \Drupal\Core\Extension\ModuleUninstallValidatorInterface for more
+ * information and examples on how to use this.
+ *
  * @param array $info
  *   The .info.yml file contents, passed by reference so that it can be altered.
  * @param \Drupal\Core\Extension\Extension $file
@@ -145,6 +151,8 @@ function hook_module_implements_alter(&$implementations, $hook) {
  * @param string $type
  *   Either 'module' or 'theme', depending on the type of .info.yml file that
  *   was passed.
+ *
+ * @see \Drupal\Core\Extension\ModuleUninstallValidatorInterface::validate()
  */
 function hook_system_info_alter(array &$info, \Drupal\Core\Extension\Extension $file, $type) {
   // Only fill this in if the .info.yml file does not define a 'datestamp'.