refactor(documentator)!: Single Instruction contract (#163)

LastDragon-ru · May 18, 2024 · 28e8444 · 28e8444
2 parents f11920e + 67b830c
commit 28e8444
Show file tree

Hide file tree

Showing 94 changed files with 1,464 additions and 914 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 The set provides best practices to make development more fun and classes/services that I found very useful while working on big extensible applications.
 
 [include:exec]: <./dev/artisan lara-asp-documentator:requirements>
-[//]: # (start: 3d045d7a4689231a18ef4436deb0b7c931a93959113b45d9f544bd2b0edcf45d)
+[//]: # (start: 5a6479e01ca04242d936b5543af76210a1af5db5468e2f480f167a2a046b62db)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Requirements
@@ -25,7 +25,7 @@ The set provides best practices to make development more fun and classes/service
 |  | `^8.22.1` |   `3.0.0 ⋯ 0.2.0`   |
 |  | `^8.0` |  `0.1.0`   |
 
-[//]: # (end: 3d045d7a4689231a18ef4436deb0b7c931a93959113b45d9f544bd2b0edcf45d)
+[//]: # (end: 5a6479e01ca04242d936b5543af76210a1af5db5468e2f480f167a2a046b62db)
 
 # Installation
 
@@ -112,14 +112,14 @@ Independent (from Laravel and Lighthouse) package that allow you to print GraphQ
 [//]: # (end: df3ee6374fabefbdeb79b26164b3f2ef88f6ed94646bb5d44751ea6da758de19)
 
 [include:file]: ./docs/Shared/Upgrading.md
-[//]: # (start: 58c515c01daf29a92b704a09f78da2fa719462cc37e47d3abde0331a7b1da0a3)
+[//]: # (start: cdb14a15bab8920d27c60204790e96bf814a9d780f6a55d5e93422db9bf56f64)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Upgrading
 
 Please follow [Upgrade Guide](UPGRADE.md).
 
-[//]: # (end: 58c515c01daf29a92b704a09f78da2fa719462cc37e47d3abde0331a7b1da0a3)
+[//]: # (end: cdb14a15bab8920d27c60204790e96bf814a9d780f6a55d5e93422db9bf56f64)
 
 # Development
 
@@ -129,7 +129,7 @@ Please follow [Upgrade Guide](UPGRADE.md).
 4. Enjoy
 
 [include:file]: ./docs/Legend.md
-[//]: # (start: a974316bcb5b40e0fcedb0c38b2c3c43c80c2cadfbf95a8caf27d6f163abff0d)
+[//]: # (start: 68b5a2c9955bc3698c6033103ab34e32d67edfcff7b726f187662b5ce2e15a67)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Legend
@@ -148,4 +148,4 @@ Please follow [Upgrade Guide](UPGRADE.md).
 |  🆆  | CI    | Running on Windows                                               |
 |  🅼  | CI    | Running on Mac OS X                                              |
 
-[//]: # (end: a974316bcb5b40e0fcedb0c38b2c3c43c80c2cadfbf95a8caf27d6f163abff0d)
+[//]: # (end: 68b5a2c9955bc3698c6033103ab34e32d67edfcff7b726f187662b5ce2e15a67)
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,7 +1,7 @@
 # Upgrade Guide
 
 [include:file]: ./docs/Shared/Upgrade.md
-[//]: # (start: 39d35167e0d4cea1b3b411d449b79f0b6df5fcbf65c5d8b9775671fe5603b7c9)
+[//]: # (start: 556e36b93ca9f82e94056295c197aa9a4c8c042054927a9bf08dd9140ad872b8)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 ## Instructions
@@ -25,7 +25,7 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases)
 | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. |
 |:--:|:--------------------------------------------------------------------------------------------------------------------|
 
-[//]: # (end: 39d35167e0d4cea1b3b411d449b79f0b6df5fcbf65c5d8b9775671fe5603b7c9)
+[//]: # (end: 556e36b93ca9f82e94056295c197aa9a4c8c042054927a9bf08dd9140ad872b8)
 
 # Packages
 

diff --git a/packages/core/README.md b/packages/core/README.md
@@ -3,7 +3,7 @@
 This package contains useful utilities and classes.
 
 [include:exec]: <../../dev/artisan lara-asp-documentator:requirements>
-[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b)
+[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Requirements
@@ -24,7 +24,7 @@ This package contains useful utilities and classes.
 |  | `^9.0.0` |   `5.0.0-beta.0 ⋯ 0.12.0`   |
 |  | `^8.22.1` |   `3.0.0 ⋯ 0.4.0`   |
 
-[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b)
+[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea)
 
 [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "core"}})
 [//]: # (start: 701034cd4b15ff1d0ee9742e3d839f3a0c70ba66d75ff6c56f712d2f69e254ae)
@@ -43,21 +43,21 @@ composer require lastdragon-ru/lara-asp-core
 Please see the [source code](./src) to find something interesting 😅
 
 [include:file]: ../../docs/Shared/Upgrading.md
-[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b)
+[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Upgrading
 
 Please follow [Upgrade Guide](UPGRADE.md).
 
-[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b)
+[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a)
 
 [include:file]: ../../docs/Shared/Contributing.md
-[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89)
+[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Contributing
 
 This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions).
 
-[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89)
+[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8)
diff --git a/packages/core/UPGRADE.md b/packages/core/UPGRADE.md
@@ -1,7 +1,7 @@
 # Upgrade Guide
 
 [include:file]: ../../docs/Shared/Upgrade.md
-[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2)
+[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 ## Instructions
@@ -25,26 +25,26 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases)
 | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. |
 |:--:|:--------------------------------------------------------------------------------------------------------------------|
 
-[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2)
+[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d)
 
 # Upgrade from v6
 
 [include:file]: ../../docs/Shared/Upgrade/FromV6.md
-[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95)
+[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151).
 
-[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95)
+[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883)
 
 * [ ] `\LastDragon_ru\LaraASP\Core\Provider\WithRoutes::bootRoutes()` requires settings.
 
 # Upgrade from v5
 
 [include:file]: ../../docs/Shared/Upgrade/FromV5.md
-[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d)
+[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 * [ ] Laravel v9 is not supported anymore. Migrate to the newer version.
 
-[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d)
+[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2)
diff --git a/packages/dev/README.md b/packages/dev/README.md
@@ -3,7 +3,7 @@
 Various internal tools and helpers to develop the package itself.
 
 [include:exec]: <../../dev/artisan lara-asp-documentator:requirements>
-[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b)
+[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Requirements
@@ -15,7 +15,7 @@ Various internal tools and helpers to develop the package itself.
 |  | `^8.1` |   `HEAD ⋯ 6.2.0`   |
 |  PHPStan  | `^1.10` |   `HEAD ⋯ 6.2.0`   |
 
-[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b)
+[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea)
 
 [include:template]: ../../docs/Shared/InstallationDev.md ({"data": {"package": "dev"}})
 [//]: # (start: e7fd13bb6d43bcc48d9fe51411b607bee0e47ccbcb1b788889f59b733865e0f1)
@@ -38,21 +38,21 @@ composer require --dev lastdragon-ru/lara-asp-dev
 _In progress_.
 
 [include:file]: ../../docs/Shared/Upgrading.md
-[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b)
+[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Upgrading
 
 Please follow [Upgrade Guide](UPGRADE.md).
 
-[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b)
+[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a)
 
 [include:file]: ../../docs/Shared/Contributing.md
-[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89)
+[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Contributing
 
 This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions).
 
-[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89)
+[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8)
diff --git a/packages/dev/UPGRADE.md b/packages/dev/UPGRADE.md
@@ -1,7 +1,7 @@
 # Upgrade Guide
 
 [include:file]: ../../docs/Shared/Upgrade.md
-[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2)
+[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 ## Instructions
@@ -25,4 +25,4 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases)
 | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. |
 |:--:|:--------------------------------------------------------------------------------------------------------------------|
 
-[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2)
+[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d)
diff --git a/packages/documentator/README.md b/packages/documentator/README.md
@@ -3,7 +3,7 @@
 This package provides various utilities for documentation generation such as Markdown Preprocessor, Requirements Dumper and more.
 
 [include:exec]: <../../dev/artisan lara-asp-documentator:requirements>
-[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b)
+[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Requirements
@@ -18,7 +18,7 @@ This package provides various utilities for documentation generation such as Mar
 |  | `^10.0.0` |   `6.1.0 ⋯ 5.0.0-beta.1`   |
 |  | `^9.21.0` |   `5.6.0 ⋯ 5.0.0-beta.1`   |
 
-[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b)
+[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea)
 
 [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "documentator"}})
 [//]: # (start: d830b5dad8950e88a29e14aa443ca509cfa19889b5c3792b00691760fb8618bb)
@@ -59,21 +59,21 @@ Generates a table with the required versions of PHP/Laravel/etc in Markdown form
 [//]: # (end: 3183e17484393f086cbec523de70a97446749151d781d55ef8f480075e5c75b9)
 
 [include:file]: ../../docs/Shared/Upgrading.md
-[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b)
+[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Upgrading
 
 Please follow [Upgrade Guide](UPGRADE.md).
 
-[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b)
+[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a)
 
 [include:file]: ../../docs/Shared/Contributing.md
-[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89)
+[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 # Contributing
 
 This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions).
 
-[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89)
+[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8)
diff --git a/packages/documentator/UPGRADE.md b/packages/documentator/UPGRADE.md
@@ -1,7 +1,7 @@
 # Upgrade Guide
 
 [include:file]: ../../docs/Shared/Upgrade.md
-[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2)
+[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 ## Instructions
@@ -25,27 +25,29 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases)
 | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. |
 |:--:|:--------------------------------------------------------------------------------------------------------------------|
 
-[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2)
+[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d)
 
 # Upgrade from v6
 
 [include:file]: ../../docs/Shared/Upgrade/FromV6.md
-[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95)
+[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151).
 
-[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95)
+[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883)
+
+* [ ] Migrate to the new contract `\LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction`.
 
 # Upgrade from v5
 
 [include:file]: ../../docs/Shared/Upgrade/FromV5.md
-[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d)
+[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 * [ ] Laravel v9 is not supported anymore. Migrate to the newer version.
 
-[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d)
+[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2)
 
 * [ ] Replace `LastDragon_ru\LaraASP\Documentator\Preprocessor\InstructionContract` by `LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction` or `LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction`.
 

diff --git a/packages/documentator/docs/Commands/preprocess.md b/packages/documentator/docs/Commands/preprocess.md
@@ -18,14 +18,22 @@ so the syntax is:
 [<instruction>]: <target>
 [<instruction>]: <target> (<parameters>)
 [<instruction>=name]: <target>
+[<instruction>=name]: <target> (<parameters>)
 ```
 
 Where:
 
 * `<instruction>` the instruction name (unknown instructions will be ignored)
 * `<target>` usually the path to the file or directory, but see the instruction description
 * `<parameters>` optional JSON string with additional parameters
-    (can be wrapped by `(...)`, `"..."`, or `'...'`)
+  (can be wrapped by `(...)`, `"..."`, or `'...'`)
+
+## Limitations
+
+* `<instruction>` will be processed everywhere in the file (eg within
+  the code block) and may give unpredictable results.
+* `<instruction>` cannot be inside text.
+* Nested `<instruction>` doesn't support.
 
 ## Instructions
 
@@ -44,7 +52,8 @@ which will be replaced to FQCN (if possible). Other tags are ignored.
 
 * `<target>` - Directory path.
 * `<parameters>` - additional parameters
-  * `depth: array|string|int|null = 0` - [Directory Depth](https://symfony.com/doc/current/components/finder.html#directory-depth) (eg the `0` means no nested directories, the `null` removes limits).
+  * `depth: array|string|int|null = 0` - [Directory Depth](https://symfony.com/doc/current/components/finder.html#directory-depth)
+    (eg the `0` means no nested directories, the `null` removes limits).
   * `template: string = 'default'` - Blade template.
 
 Returns the list of `*.md` files in the `<target>` directory. Each file
@@ -53,7 +62,7 @@ after the Header will be used as a summary.
 
 ### `[include:example]: <target>`
 
-* `<target>` - Example file path.
+* `<target>` - File path.
 
 Includes contents of the `<target>` file as an example wrapped into
 ` ```code block``` `. It also searches for `<target>.run` file, execute
@@ -98,13 +107,6 @@ used to determine package name and summary.
 
 Includes the `<target>` as a template.
 
-## Limitations
-
-* `<instruction>` will be processed everywhere in the file (eg within
-  the code block) and may give unpredictable results.
-* `<instruction>` cannot be inside text.
-* Nested `<instruction>` doesn't support.
-
 ## Arguments
 
 ### `path?`