Document

package_manager/src/StageBase.php

@@ -201,8 +201,6 @@ abstract class StageBase implements LoggerAwareInterface {
   /**
    * Gets the stage type.
    *
-   * The recommended pattern is `MODULE:SUB_TYPE`.
-   *
    * @return string
    *   The stage type.
    *
@@ -224,11 +222,22 @@ abstract class StageBase implements LoggerAwareInterface {
   /**
    * Returns the stage type.
    *
+   * The stage type is the way a particular type of stage "identifies itself" to
+   * calling code. It is similar to a plugin ID. If external code needs to know
+   * exactly what sort of stage it's dealing with -- an unattended core updater,
+   * say, or a contributed project installer -- it should check the stage type.
+   *
    * All concrete subclasses MUST explicitly implement this method, even if all
-   * they do is call the parent method.
+   * they do is call the parent method. Since the stage type is the "source of
+   * truth" for calling code (including event subscribers) to know what kind of
+   * stage this is, this restriction ensures that a stage which extends another
+   * stage does not accidentally inherit its parent's type unless the
+   * programmer intends it.
    *
    * @return string
-   *   The stage type.
+   *   The stage type. It is recommended that this be prefixed with the name of
+   *   the providing module, like `MODULE_NAME:STAGE_TYPE`. For example,
+   *   `package_manager:generic`.
    */
   abstract protected function type(): string;