From 68d762d845ceffb057f2393d85e68083e09c0ec0 Mon Sep 17 00:00:00 2001
From: Brandon Lira <brandonlira98@gmail.com>
Date: Mon, 24 Mar 2025 20:52:30 -0300
Subject: [PATCH 1/2] Issue #3200162: Improve documentation for Graph component

---
 core/lib/Drupal/Component/Graph/Graph.php | 46 ++++++++++++-----------
 1 file changed, 25 insertions(+), 21 deletions(-)

diff --git a/core/lib/Drupal/Component/Graph/Graph.php b/core/lib/Drupal/Component/Graph/Graph.php
index d0a9381a54ea..d894d791f99b 100644
--- a/core/lib/Drupal/Component/Graph/Graph.php
+++ b/core/lib/Drupal/Component/Graph/Graph.php
@@ -4,6 +4,25 @@
 
 /**
  * Directed acyclic graph manipulation.
+ *
+ * This class represents a directed acyclic graph (DAG) and provides methods
+ * for processing and sorting it.
+ *
+ * Example of a graph structure:
+ * @code
+ *   1────►2────►3
+ *         │     │
+ *         │     ▼
+ *         └───► 4
+ * @endcode
+ *
+ * Example of defining a graph in PHP:
+ * @code
+ *   $graph[1]['edges'][2] = 1;
+ *   $graph[2]['edges'][3] = 1;
+ *   $graph[2]['edges'][4] = 1;
+ *   $graph[3]['edges'][4] = 1;
+ * @endcode
  */
 class Graph {
 
@@ -15,29 +34,14 @@ class Graph {
   protected $graph;
 
   /**
-   * Instantiates the depth first search object.
+   * Instantiates the directed acyclic graph object.
    *
    * @param array $graph
-   *   A three dimensional associated array, with the first keys being the names
-   *   of the vertices, these can be strings or numbers. The second key is
-   *   'edges' and the third one are again vertices, each such key representing
-   *   an edge. Values of array elements are copied over.
-   *
-   *   Example:
-   *   @code
-   *     $graph[1]['edges'][2] = 1;
-   *     $graph[2]['edges'][3] = 1;
-   *     $graph[2]['edges'][4] = 1;
-   *     $graph[3]['edges'][4] = 1;
-   *   @endcode
-   *
-   *   On return you will also have:
-   *   @code
-   *     $graph[1]['paths'][2] = 1;
-   *     $graph[1]['paths'][3] = 1;
-   *     $graph[2]['reverse_paths'][1] = 1;
-   *     $graph[3]['reverse_paths'][1] = 1;
-   *   @endcode
+   *   A three-dimensional associative array, with the first keys being the names
+   *   of the vertices, which can be strings or numbers. The second key is
+   *   'edges', whose value is an array keyed by the names of the vertices
+   *   connected to it; the values in this array can be simply TRUE or may
+   *   contain other data.
    */
   public function __construct($graph) {
     $this->graph = $graph;
-- 
GitLab


From 5931f95e42339f0e7cf5c071b2fd353b23ab64b1 Mon Sep 17 00:00:00 2001
From: Brandon Lira <brandonlira98@gmail.com>
Date: Mon, 24 Mar 2025 20:57:48 -0300
Subject: [PATCH 2/2] Issue #3200162: coding standard

---
 core/lib/Drupal/Component/Graph/Graph.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/core/lib/Drupal/Component/Graph/Graph.php b/core/lib/Drupal/Component/Graph/Graph.php
index d894d791f99b..63f345d4f20a 100644
--- a/core/lib/Drupal/Component/Graph/Graph.php
+++ b/core/lib/Drupal/Component/Graph/Graph.php
@@ -37,8 +37,8 @@ class Graph {
    * Instantiates the directed acyclic graph object.
    *
    * @param array $graph
-   *   A three-dimensional associative array, with the first keys being the names
-   *   of the vertices, which can be strings or numbers. The second key is
+   *   A three-dimensional associative array, with the first keys being the
+   *   names of the vertices, which can be strings or numbers. The second key is
    *   'edges', whose value is an array keyed by the names of the vertices
    *   connected to it; the values in this array can be simply TRUE or may
    *   contain other data.
-- 
GitLab