Issue #3111463 by dww, benjifisher, xjm: Improve code documentation for \Drupal\update\ProjectSecurityData

(cherry picked from commit 68c5399a7f)

core/modules/update/src/ProjectSecurityData.php

@@ -17,6 +17,12 @@ final class ProjectSecurityData {
    * For example, if this value is 2 and the existing version is 9.0.1, the
    * 9.0.x branch will receive security coverage until the release of version
    * 9.2.0.
+   *
+   * @todo In https://www.drupal.org/node/2998285 determine if we want this
+   *   policy to be expressed in the updates.drupal.org feed, instead of relying
+   *   on a hard-coded constant.
+   *
+   * @see https://www.drupal.org/core/release-cycle-overview
    */
   const CORE_MINORS_WITH_SECURITY_COVERAGE = 2;
 
@@ -144,6 +150,12 @@ final class ProjectSecurityData {
   /**
    * Gets the release the current minor will receive security coverage until.
    *
+   * For the sake of example, assume that the currently installed version of
+   * Drupal is 8.7.11 and that static::CORE_MINORS_WITH_SECURITY_COVERAGE is 2.
+   * When Drupal 8.9.0 is released, the supported minor versions will be 8.8
+   * and 8.9. At that point, Drupal 8.7 will no longer have security
+   * coverage. Therefore, this function would return "8.9.0".
+   *
    * @todo In https://www.drupal.org/node/2998285 determine how we will know
    *    what the final minor release of a particular major version will be. This
    *    method should not return a version beyond that minor.
@@ -165,7 +177,33 @@ final class ProjectSecurityData {
   }
 
   /**
-   * Gets the number of additional minor security covered releases.
+   * Gets the number of additional minor releases with security coverage.
+   *
+   * This function compares the currently installed (existing) version of
+   * the project with two things:
+   * - The latest available official release of that project.
+   * - The target minor release where security coverage for the current release
+   *   should expire. This target release is determined by
+   *   getSecurityCoverageUntilVersion().
+   *
+   * For the sake of example, assume that the currently installed version of
+   * Drupal is 8.7.11 and that static::CORE_MINORS_WITH_SECURITY_COVERAGE is 2.
+   *
+   * Before the release of Drupal 8.8.0, this function would return 2.
+   *
+   * After the release of Drupal 8.8.0 and before the release of 8.9.0, this
+   * function would return 1 to indicate that the next minor version release
+   * will end security coverage for 8.7.
+   *
+   * When Drupal 8.9.0 is released, this function would return 0 to indicate
+   * that security coverage is over for 8.7.
+   *
+   * If the currently installed version is 9.0.0, and there is no 9.1.0 release
+   * yet, the function would return 2. Once 9.1.0 is out, it would return 1.
+   * When 9.2.0 is released, it would again return 0.
+   *
+   * Note: callers should not test this function's return value with empty()
+   * since 0 is a valid return value that has different meaning than NULL.
    *
    * @param string $security_covered_version
    *   The version until which the existing version receives security coverage.
@@ -173,6 +211,8 @@ final class ProjectSecurityData {
    * @return int|null
    *   The number of additional minor releases that receive security coverage,
    *   or NULL if this cannot be determined.
+   *
+   * @see \Drupal\update\ProjectSecurityData\getSecurityCoverageUntilVersion()
    */
   private function getAdditionalSecurityCoveredMinors($security_covered_version) {
     $security_covered_version_major = ModuleVersion::createFromVersionString($security_covered_version)->getMajorVersion();
@@ -181,17 +221,16 @@ final class ProjectSecurityData {
       $release_version = ModuleVersion::createFromVersionString($release['version']);
       if ($release_version->getMajorVersion() === $security_covered_version_major && $release['status'] === 'published' && !$release_version->getVersionExtra()) {
         // The releases are ordered with the most recent releases first.
-        // Therefore if we have found an official, published release with the
+        // Therefore, if we have found a published, official release with the
-        // same major version as $security_covered_version then this release
+        // same major version as $security_covered_version, then this release
         // can be used to determine the latest minor.
         $latest_minor = $this->getSemanticMinorVersion($release['version']);
         break;
       }
     }
-    // If $latest_minor is set, we know that $latest_minor and
+    // If $latest_minor is set, we know that $security_covered_version_minor and
-    // $security_covered_version_minor have the same major version. Therefore we
+    // $latest_minor have the same major version. Therefore, we can subtract to
-    // can simply subtract to determine the number of additional minor security
+    // determine the number of additional minor releases with security coverage.
-    // covered releases.
     return isset($latest_minor) ? $security_covered_version_minor - $latest_minor : NULL;
   }