doc: expand description of parseArg's default

[bakkot]

Per #53427 (comment).

[shadowspawn]

From past experience, it is hard being clear about the config setup, the passed arguments, and the parsed result! I often say command-line but that does not cover custom arguments.

The suggested text does not accurately cover strict:false mode.

I'll have a try, instead try changing the initial description:

- The default option value when this argument is not passed.
+ The default option value when the option is not included in the arguments to parse.

[bakkot]

I always forget about strict: false. Happy to take suggestions for more precision there.

[RedYetiDev]

Suggested change

	`type` property. When `multiple` is `true`, it must be an array. For
	`string` arguments, if the option is passed it must still be followed by
	a value.
	`type` property. When `multiple` is `true`, it must be an array.

In my personal opinion, saying "The default option value when this argument is not passed." implies that if it passed, it must have a value.

Secondly, "it must still be followed by a value." makes it sound like the "default" option doesn't work on string arguments...

[bakkot]

makes it sound like the "default" option doesn't work on string arguments.

The default option doesn't do anything when the option being specified is passed (except in strict: false), so that's a correct inference (as long as you don't skip over the "if the option is passed" part). Unless I'm misunderstanding you?

[RedYetiDev]

I think "it must still be followed by a value" is redudant because of "The default option value when this argument is not passed.", but that might just be me.

[shadowspawn]

Another possible wording (which I used in a recent comment where I was trying to clarify behaviour):

The default value is only used when the option does not appear in the arguments to be parsed. 

[bakkot]

Tried a new wording based on @shadowspawn's suggestion, WDYT?

default {string | boolean | string[] | boolean[]} The default value to be used if (and only if) the option does not appear in the arguments to be parsed.

Hopefully that's sufficient to prevent people from coming to (incorrectly) believe that setting this would allow passing string-based options without arguments in strict: true.

[shadowspawn]

Nice! Big +1 from me.

[shadowspawn]

Small but solid incremental improvement, reducing chance for confusion.

[bakkot]

Friendly ping. Not sure if there's a docs team I should @?