From 52854f31b131c6fe1cd6c7135e11a8fb94d6643e Mon Sep 17 00:00:00 2001
From: Benedikt Franke <benedikt.franke@mll.com>
Date: Thu, 19 Dec 2024 12:09:12 +0100
Subject: [PATCH] Format docs

---
 Makefile                |   8 ++-
 docs/class-reference.md | 128 +++++++++++++++++++++++++++++++++++-----
 2 files changed, 118 insertions(+), 18 deletions(-)

diff --git a/Makefile b/Makefile
index c21b08589..e251674a8 100644
--- a/Makefile
+++ b/Makefile
@@ -3,13 +3,13 @@ it: fix stan test docs ## Run the commonly used targets
 
 .PHONY: help
 help: ## Displays this list of targets with descriptions
-	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
+	@grep --extended-regexp '^[a-zA-Z0-9_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
 
 .PHONY: setup
 setup: vendor phpstan.neon ## Set up the project
 
 .PHONY: fix
-fix: rector php-cs-fixer ## Automatic code fixes
+fix: rector php-cs-fixer prettier ## Automatic code fixes
 
 .PHONY: rector
 rector: vendor ## Automatic code fixes with Rector
@@ -19,6 +19,10 @@ rector: vendor ## Automatic code fixes with Rector
 php-cs-fixer: vendor ## Fix code style
 	composer php-cs-fixer
 
+.PHONY: prettier
+prettier: ## Format code with prettier
+	prettier --write --tab-width=2 *.md **/*.md
+
 phpstan.neon:
 	printf "includes:\n  - phpstan.neon.dist" > phpstan.neon
 
diff --git a/docs/class-reference.md b/docs/class-reference.md
index 26922b7fc..63102a358 100644
--- a/docs/class-reference.md
+++ b/docs/class-reference.md
@@ -430,37 +430,35 @@ public $variableValues;
 
 ```php
 /**
- * Helper method that returns names of all fields selected in query for
- * $this->fieldName up to $depth levels.
+ * Returns names of all fields selected in query for `$this->fieldName` up to `$depth` levels.
  *
  * Example:
- * query MyQuery{
  * {
  *   root {
- *     id,
+ *     id
  *     nested {
- *      nested1
- *      nested2 {
- *        nested3
- *      }
+ *       nested1
+ *       nested2 {
+ *         nested3
+ *       }
  *     }
  *   }
  * }
  *
- * Given this ResolveInfo instance is a part of "root" field resolution, and $depth === 1,
- * method will return:
+ * Given this ResolveInfo instance is a part of root field resolution, and $depth === 1,
+ * this method will return:
  * [
  *     'id' => true,
  *     'nested' => [
- *         nested1 => true,
- *         nested2 => true
- *     ]
+ *         'nested1' => true,
+ *         'nested2' => true,
+ *     ],
  * ]
  *
- * Warning: this method it is a naive implementation which does not take into account
- * conditional typed fragments. So use it with care for fields of interface and union types.
+ * This method does not consider conditional typed fragments.
+ * Use it with care for fields of interface and union types.
  *
- * @param int $depth How many levels to include in output
+ * @param int $depth How many levels to include in the output beyond the first
  *
  * @return array<string, mixed>
  *
@@ -469,6 +467,104 @@ public $variableValues;
 function getFieldSelection(int $depth = 0): array
 ```
 
+```php
+/**
+ * Returns names and args of all fields selected in query for `$this->fieldName` up to `$depth` levels, including aliases.
+ *
+ * The result maps original field names to a map of selections for that field, including aliases.
+ * For each of those selections, you can find the following keys:
+ * - "args" contains the passed arguments for this field/alias
+ * - "selectionSet" contains potential nested fields of this field/alias. The structure is recursive from here.
+ *
+ * Example:
+ * {
+ *   root {
+ *     id
+ *     nested {
+ *      nested1(myArg: 1)
+ *      nested1Bis: nested1
+ *     }
+ *     alias1: nested {
+ *       nested1(myArg: 2, mySecondAg: "test")
+ *     }
+ *   }
+ * }
+ *
+ * Given this ResolveInfo instance is a part of "root" field resolution, and $depth === 1,
+ * this method will return:
+ * [
+ *     'id' => [
+ *         'id' => [
+ *              'args' => [],
+ *         ],
+ *     ],
+ *     'nested' => [
+ *         'nested' => [
+ *             'args' => [],
+ *             'selectionSet' => [
+ *                 'nested1' => [
+ *                     'nested1' => [
+ *                          'args' => [
+ *                              'myArg' => 1,
+ *                          ],
+ *                      ],
+ *                      'nested1Bis' => [
+ *                          'args' => [],
+ *                      ],
+ *                 ],
+ *             ],
+ *          ],
+ *          'alias1' => [
+ *             'args' => [],
+ *             'selectionSet' => [
+ *                  'nested1' => [
+ *                      'nested1' => [
+ *                           'args' => [
+ *                               'myArg' => 2,
+ *                               'mySecondAg' => "test,
+ *                           ],
+ *                      ],
+ *                  ],
+ *              ],
+ *         ],
+ *     ],
+ * ]
+ *
+ * This method does not consider conditional typed fragments.
+ * Use it with care for fields of interface and union types.
+ * You can still alias the union type fields with the same name in order to extract their corresponding args.
+ *
+ * Example:
+ * {
+ *   root {
+ *     id
+ *     unionPerson {
+ *       ...on Child {
+ *         name
+ *         birthdate(format: "d/m/Y")
+ *       }
+ *       ...on Adult {
+ *         adultName: name
+ *         adultBirthDate: birthdate(format: "Y-m-d")
+ *         job
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * @param int $depth How many levels to include in the output beyond the first
+ *
+ * @throws \Exception
+ * @throws Error
+ * @throws InvariantViolation
+ *
+ * @return array<string, mixed>
+ *
+ * @api
+ */
+function getFieldSelectionWithAliases(int $depth = 0): array
+```
+
 ## GraphQL\Language\DirectiveLocation
 
 Enumeration of available directive locations.