From 707501cea282e87f2a71aa6004514f84f3935235 Mon Sep 17 00:00:00 2001
From: Michael Molisani <git@molisani.us>
Date: Sat, 2 Nov 2024 15:06:30 -0400
Subject: [PATCH] docs: describe placeholder option for positional args

Signed-off-by: Michael Molisani <git@molisani.us>
Signed-off-by: Michael Molisani <mmolisani@bloomberg.net>
---
 .../examples/placeholder-argument.txt         | 27 +++++++++++++++++++
 .../features/argument-parsing/positional.mdx  | 10 +++++++
 2 files changed, 37 insertions(+)
 create mode 100644 docs/docs/features/argument-parsing/examples/placeholder-argument.txt

diff --git a/docs/docs/features/argument-parsing/examples/placeholder-argument.txt b/docs/docs/features/argument-parsing/examples/placeholder-argument.txt
new file mode 100644
index 0000000..42e8715
--- /dev/null
+++ b/docs/docs/features/argument-parsing/examples/placeholder-argument.txt
@@ -0,0 +1,27 @@
+import { buildCommand, type CommandContext } from "@stricli/core";
+
+export const root = buildCommand({
+  func(this: CommandContext, _: {}, src: string, dest: string) {
+    this.process.stdout.write(`Copying file from ${src} to ${dest}`);
+  },
+  parameters: {
+    positional: {
+      kind: "tuple",
+      parameters: [
+        {
+          brief: "Source file",
+          parse: String,
+          placeholder: "src",
+        },
+        {
+          brief: "Destination path",
+          parse: String,
+          placeholder: "dest",
+        },
+      ],
+    },
+  },
+  docs: {
+    brief: "Example for live playground with positional arguments labeled by placeholders",
+  },
+});
diff --git a/docs/docs/features/argument-parsing/positional.mdx b/docs/docs/features/argument-parsing/positional.mdx
index 5141bfd..f4bcc26 100644
--- a/docs/docs/features/argument-parsing/positional.mdx
+++ b/docs/docs/features/argument-parsing/positional.mdx
@@ -67,3 +67,13 @@ import DefaultTupleArgumentCode from "./examples/default-tuple-argument.txt";
 <StricliPlayground filename="default-tuple-argument" rootExport="root" appName="run" defaultInput="">
     {DefaultTupleArgumentCode}
 </StricliPlayground>
+
+## Placeholder
+
+Positional arguments don't truly have names as a name cannot be included in the input (for named arguments, use [flags](./flags.mdx) instead). However, they still have a semantic meaning and it can be useful to refer to it with a name for simplicity. To avoid confusion with named flags, you can specify a "placeholder" for positional arguments. These placeholders are used in the auto-generated usage lines and in the help text.
+
+import PlaceholderArgumentCode from "./examples/placeholder-argument.txt";
+
+<StricliPlayground filename="placeholder-argument" rootExport="root" appName="run" defaultInput="--help">
+    {PlaceholderArgumentCode}
+</StricliPlayground>