add examples to flags

Author: Elektryk-Andrzej

Code/FlagSystem/Flags/Flag.cs

@@ -15,7 +15,8 @@ public readonly record struct Argument(
         string Name, 
         string Description, 
         Func<string[], Result> Handler, 
-        bool IsRequired
+        bool IsRequired,
+        string Example
     ) {
         public Result AddArgument(string[] values) => Handler(values);
     }

Code/FlagSystem/Flags/FunctionFlag.cs

@@ -39,7 +39,8 @@ public class FunctionFlag : Flag
                 _expectedVarTokens.Add(token);
                 return true;
             },
-            true
+            true,
+            "-- argument $name"
         )
     ];
 

Code/FlagSystem/Flags/OnCustomTriggerFlag.cs

@@ -30,7 +30,8 @@ public class OnCustomTriggerFlag : Flag
             ScriptsBoundToTrigger.AddOrInitListWithKey(_trigger, ScriptName);
             return true;
         },
-        true
+        true,
+        "!-- OnCustomTrigger myTrigger"
     );
 
     public override Argument[] Arguments => [];

Code/FlagSystem/Flags/OnEventFlag.cs

@@ -13,8 +13,11 @@ public class OnEventFlag : Flag
     private Safe<string> _event;
 
     public override string Description =>
-        "Binds a script to an in-game event. When the event happens, the script will execute. " +
-        "Events can sometimes also carry information of their own, ";
+        """
+        Binds a script to an in-game event. 
+        When the event happens, the script will execute. 
+        Find events using 'serhelp events' command.
+        """;
 
     public override Argument? InlineArgument => new(
         "eventName",
@@ -37,7 +40,8 @@ public class OnEventFlag : Flag
 
             return true;
         },
-        true
+        true,
+        "!-- OnEvent RoundStarted"
     );
 
     public override Result OnScriptRunning(Script scr)

Code/Plugin/Commands/HelpSystem/DocsProvider.cs

@@ -232,38 +232,39 @@ private static string GetFlagInfo(string flagName)
             .Select(arg => $"-- {arg.Name} ...")
             .JoinStrings("\n");
 
-        StringBuilder argumentDescription = new();
+        StringBuilder argDesc = new();
         if (flag.InlineArgument.HasValue)
         {
-            argumentDescription.AppendLine($"  Inline argument '{flag.InlineArgument.Value.Name}':");
-            argumentDescription.AppendLine($"  > {flag.InlineArgument.Value.Description}");
-            argumentDescription.AppendLine();
+            argDesc.AppendLine(
+                (flag.InlineArgument.Value.IsRequired ? "> Required" : "> Optional") 
+                + $" inline argument '{flag.InlineArgument.Value.Name}':"
+            );
+            argDesc.AppendLine($"{flag.InlineArgument.Value.Description}");
+            argDesc.AppendLine("> Example usage");
+            argDesc.AppendLine(flag.InlineArgument.Value.Example);
+            argDesc.AppendLine();
         }
 
         foreach (var arg in flag.Arguments)
         {
-            argumentDescription.AppendLine($"  Additional argument '{arg.Name}':");
-            argumentDescription.AppendLine($"  > {arg.Description}");
-            
-            if (!arg.IsRequired)
-            {
-                argumentDescription.AppendLine($"  > This argument is not required for the flag to operate");
-            }
-            
-            argumentDescription.AppendLine();
+            argDesc.AppendLine((arg.IsRequired ? "> Required" : "> Optional") + $" argument '{arg.Name}':");
+            argDesc.AppendLine($"{arg.Description}");
+            argDesc.AppendLine("> Example usage");
+            argDesc.AppendLine(arg.Example);
+            argDesc.AppendLine();
         }
 
         return
             $"""
              ===== {flagName} =====
-             > {flag.Description}
+             {flag.Description}
              
              Usage:
              !-- {flagName} {inlineArgumentUsage}
              {argumentsUsage}
              
-             {(argumentDescription.Length > 0 ? "Arguments:" : "")}
-             {argumentDescription}
+             {(argDesc.Length > 0 ? "+++ Arguments +++" : "")}
+             {argDesc}
              """;
     }