From 6d25f705f682746026d5a6d79179d54db37713c8 Mon Sep 17 00:00:00 2001
From: quietone <quietone@2572884.no-reply.drupal.org>
Date: Fri, 25 Apr 2025 20:58:30 +1200
Subject: [PATCH] Issue #3200162 by brandonlira, ksenzee, ultimike, larowlan,
 cecelias, xjm: 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..63f345d4f20a 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