wip: docs reminders

v3_occ_vs_vals.md

@@ -0,0 +1,19 @@
+# Flags
+
+-f?
+-f*
+-f{$0,3}: flags can't be required by default, hence always 0 or more (bounded/unbounded)
+
+# Options
+
+-o val
+-o val?
+-o val*
+-o val+
+-o val{0,3}
+
+(-o val){0,3}
+(-o val?){0,3}
+(-o val*){0,3}
+(-o val+){0,3}
+(-o val{0,3}){0,3}

v3_warn_cases.md

@@ -0,0 +1,81 @@
+These are cases which could be detected by `clap`, and potentially warn at compile time. Maybe even with a nice web URL to more info.
+
+# Abrv. Syntax
+
+First, a little about the syntax to understand the setup of rule. This syntax will make each rule more concise so we don't have to write an entire `clap` definition.
+
+## Arg Types
+
+* `--opt` is an option
+* `--flag` is a flag
+* `#` (i.e. `1` or `2`) is a positional argument
+* `val` is an option value
+
+## Modifiers
+
+Can be used on `val` or Arg types
+
+* `*`: zero or more
+* `+`: one or more
+* `?`: zero or one
+* `{#,#}`: # to # times (i.e. `{1,4}` is one to four times)
+* `<>`: required
+* `=`: requires equals
+* Ends in `,`: requires delimiter
+* `(foo,bar)`: values can only be `foo` or `bar`
+
+# --opt val? 1
+
+## Ambiguous Uses
+
+```
+$ prog --opt foo
+# is foo option val or positional?
+```
+
+## Non-Ambiguous Uses
+
+```
+$ prog 1 --opt
+$ prog --opt -- 1
+```
+
+## Fixes
+
+### Require equals on `--opt`
+
+```
+$ prog --opt foo
+# foo is positional
+
+$ prog --opt=val foo
+```
+
+# --opt val+ 1
+
+## Ambiguous Uses
+
+```
+$ prog --opt foo bar
+# is bar option val or positional?
+```
+
+## Non-Ambiguous Uses
+
+```
+$ prog 1 --opt val
+$ prog --opt val -- 1
+```
+
+## Fixes
+
+### `--opt` only one val per occurrence
+
+```
+$ prog --opt foo bar
+# bar is positional
+
+$ prog --opt val bar --opt foo
+# bar is positional
+```
+