Enhance maml template generation with annotated comments and update maml/maml to v3.2

Author: antonmedv

composer.json

@@ -42,7 +42,7 @@
     ],
     "require": {
         "php": "^8.3",
-        "maml/maml": "^3.1",
+        "maml/maml": "^3.2",
         "symfony/console": "^7.4.0 || ^8.0.0",
         "symfony/process": "^7.4.0 || ^8.0.0",
         "symfony/yaml": "^7.4.0 || ^8.0.0"

src/Command/InitCommand.php

@@ -11,6 +11,7 @@
 namespace Deployer\Command;
 
 use Deployer\Deployer;
+use Maml\Annotated;
 use Maml\Maml;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
@@ -168,20 +169,27 @@ private function php(string $template, string $project, string $repository, arra
     private function maml(string $template, string $project, string $repository, array $hosts): string
     {
         $recipe = [
-            "import" => [
+            "import" => Annotated::with([
                 "recipe/$template.php",
-            ],
-            "config" => [
+            ])->comment(
+                ' You can import other php or maml recipes.',
+                ' Import recipes directly from recipe/ folder.',
+            ),
+            "config" => Annotated::with([
                 "repository" => "$repository",
-            ],
+            ])->emptyLineBefore(),
             "hosts" => [],
-            "tasks" => [
+            "tasks" => Annotated::with([
                 "example" => [
                     [
                         "run" => "date",
+                        "cwd" => "~",
                     ],
                 ],
-            ],
+            ])->emptyLineBefore()->comment(
+                ' Define tasks as list of steps to run,',
+                ' or use array to strings to define group task.',
+            ),
         ];
 
         foreach ($hosts as $host) {
@@ -191,6 +199,12 @@ private function maml(string $template, string $project, string $repository, arr
             ];
         }
 
+        $recipe['hosts'] = Annotated::with($recipe['hosts'])
+            ->emptyLineBefore()
+            ->comment(
+                ' Hosts',
+            );
+
         return Maml::stringify($recipe);
     }