Allow defining a help string for an option's parameter value.

Allow defining a help string for an option's parameter value.

BUG= https://code.google.com/p/dart/issues/detail?id=5201
R=nweiz@google.com

Committed: https://code.google.com/p/dart/source/detail?r=38047

[nweiz, 2014-07-02 19:41:33]

https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md
File pkg/args/CHANGELOG.md (right):

https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md#newcode3
pkg/args/CHANGELOG.md:3: * Options may define `valueHelp` which will then be
shown in the usage.
"valueHelp" -> "helpValue"

I find both of these names confusing though. What do you think about
"valueName"?

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md
File pkg/args/README.md (left):

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md#oldcode238
pkg/args/README.md:238: lines. This provides spatial diversity between options.
This change should probably also be mentioned in the changelog.

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md
File pkg/args/README.md (right):

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md#newcode212
pkg/args/README.md:212: For non-flag options, you can also provide a help string
for the parameter:
"help string" -> "name"

[Sean Eagan, 2014-07-02 20:59:57]

On 2014/07/02 19:41:33, nweiz wrote:
> https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md
> File pkg/args/CHANGELOG.md (right):
> 
>
https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md#newcode3
> pkg/args/CHANGELOG.md:3: * Options may define `valueHelp` which will then be
> shown in the usage.
> "valueHelp" -> "helpValue"
> 
> I find both of these names confusing though. What do you think about
> "valueName"?
> 
> https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md
> File pkg/args/README.md (left):
> 
> https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md#oldcode238
> pkg/args/README.md:238: lines. This provides spatial diversity between
options.
> This change should probably also be mentioned in the changelog.
> 
> https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md
> File pkg/args/README.md (right):
> 
> https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md#newcode212
> pkg/args/README.md:212: For non-flag options, you can also provide a help
string
> for the parameter:
> "help string" -> "name"

[Sean Eagan, 2014-07-02 21:10:50]

On 2014/07/02 19:41:33, nweiz wrote:
> pkg/args/CHANGELOG.md:3: * Options may define `valueHelp` which will then be
> shown in the usage.
> "valueHelp" -> "helpValue"
> 
> I find both of these names confusing though. What do you think about
> "valueName"?

"valueHelp" isn't bad, but "valueLabel" is a little more descriptive I think.

To me, "valueName" suggests it can only be a single word, which is probably
ideal, but not sure that it should actually be restricted.

Elsewhere I have seen it called "metaVar", of which I am not a fan.

[nweiz, 2014-07-02 21:20:00]

On 2014/07/02 21:10:50, Sean Eagan wrote:
> On 2014/07/02 19:41:33, nweiz wrote:
> > pkg/args/CHANGELOG.md:3: * Options may define `valueHelp` which will then be
> > shown in the usage.
> > "valueHelp" -> "helpValue"
> > 
> > I find both of these names confusing though. What do you think about
> > "valueName"?
> 
> "valueHelp" isn't bad, but "valueLabel" is a little more descriptive I think.
> 
> To me, "valueName" suggests it can only be a single word, which is probably
> ideal, but not sure that it should actually be restricted.
> 
> Elsewhere I have seen it called "metaVar", of which I am not a fan.

"valueLabel" makes me think it's going to be the label of one possible
value—what's actually called "allowedHelp".

I don't think "valueName" implies that it has to be a single word. Names can be
multiple words; they just tend to be more verbose that way, which reflects how
this name would be used.

[Sean Eagan, 2014-07-03 19:20:34]

On 2014/07/02 21:20:00, nweiz wrote:
> On 2014/07/02 21:10:50, Sean Eagan wrote:
> > On 2014/07/02 19:41:33, nweiz wrote:
> > > pkg/args/CHANGELOG.md:3: * Options may define `valueHelp` which will then
be
> > > shown in the usage.
> > > "valueHelp" -> "helpValue"
> > > 
> > > I find both of these names confusing though. What do you think about
> > > "valueName"?
> > 
> > "valueHelp" isn't bad, but "valueLabel" is a little more descriptive I
think.
> > 
> > To me, "valueName" suggests it can only be a single word, which is probably
> > ideal, but not sure that it should actually be restricted.
> > 
> > Elsewhere I have seen it called "metaVar", of which I am not a fan.
> 
> "valueLabel" makes me think it's going to be the label of one possible
> value—what's actually called "allowedHelp".
> 
> I don't think "valueName" implies that it has to be a single word. Names can
be
> multiple words; they just tend to be more verbose that way, which reflects how
> this name would be used.

I guess that could be said of anything with the "value" prefix.  The "meta"
prefix is kind of growing on me:

    metaLabel
    metaName
    metaHelp

But mostly I'm just excited to start using it :).

[Bob Nystrom, 2014-07-07 20:37:20]

On 2014/07/03 19:20:34, Sean Eagan wrote:
> On 2014/07/02 21:20:00, nweiz wrote:
> > On 2014/07/02 21:10:50, Sean Eagan wrote:
> > > On 2014/07/02 19:41:33, nweiz wrote:
> > > > pkg/args/CHANGELOG.md:3: * Options may define `valueHelp` which will
then
> be
> > > > shown in the usage.
> > > > "valueHelp" -> "helpValue"
> > > > 
> > > > I find both of these names confusing though. What do you think about
> > > > "valueName"?
> > > 
> > > "valueHelp" isn't bad, but "valueLabel" is a little more descriptive I
> think.
> > > 
> > > To me, "valueName" suggests it can only be a single word, which is
probably
> > > ideal, but not sure that it should actually be restricted.
> > > 
> > > Elsewhere I have seen it called "metaVar", of which I am not a fan.
> > 
> > "valueLabel" makes me think it's going to be the label of one possible
> > value—what's actually called "allowedHelp".
> > 
> > I don't think "valueName" implies that it has to be a single word. Names can
> be
> > multiple words; they just tend to be more verbose that way, which reflects
how
> > this name would be used.
> 
> I guess that could be said of anything with the "value" prefix.  The "meta"
> prefix is kind of growing on me:
> 
>     metaLabel
>     metaName
>     metaHelp

Well, "meta" is a prefix, not a word, so that would be "metalabel", etc. But I'm
not a fan of that. "Meta" doesn't really mean anything here. I think "help" is
clearer and matches other parameters ("help", "allowedHelp").

> But mostly I'm just excited to start using it :).

Thanks for your patience! :)

- bob

[Bob Nystrom, 2014-07-07 20:37:35]

https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md
File pkg/args/CHANGELOG.md (right):

https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md#newcode3
pkg/args/CHANGELOG.md:3: * Options may define `valueHelp` which will then be
shown in the usage.
On 2014/07/02 19:41:32, nweiz wrote:
> "valueHelp" -> "helpValue"
> 
> I find both of these names confusing though. What do you think about
> "valueName"?

I want to include "help" in the name to make it clear that that's what it's for
and that it doesn't have any other effect. I think "valueHelp" matches
"allowedHelp" pretty well.

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md
File pkg/args/README.md (left):

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md#oldcode238
pkg/args/README.md:238: lines. This provides spatial diversity between options.
On 2014/07/02 19:41:32, nweiz wrote:
> This change should probably also be mentioned in the changelog.

There's no behavioral change here. I just took the bit out of the README because
I never really liked the wording of that paragraph. :(

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md
File pkg/args/README.md (right):

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md#newcode212
pkg/args/README.md:212: For non-flag options, you can also provide a help string
for the parameter:
On 2014/07/02 19:41:32, nweiz wrote:
> "help string" -> "name"

I think I like "help string" here. I want people to understand the name doesn't
affect how they access the arg programmatically.

[nweiz, 2014-07-07 20:52:00]

lgtm

I do really think using "help" to describe the name of a value is misleading,
but do what you want.

https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md
File pkg/args/CHANGELOG.md (right):

https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md#newcode3
pkg/args/CHANGELOG.md:3: * Options may define `valueHelp` which will then be
shown in the usage.
On 2014/07/07 20:37:34, Bob Nystrom wrote:
> On 2014/07/02 19:41:32, nweiz wrote:
> > "valueHelp" -> "helpValue"
> > 
> > I find both of these names confusing though. What do you think about
> > "valueName"?
> 
> I want to include "help" in the name to make it clear that that's what it's
for
> and that it doesn't have any other effect. I think "valueHelp" matches
> "allowedHelp" pretty well.

I think "help" communicates that it's some sort of prose documentation, rather
than an individual name. That's what it means when it's used elsewhere in this
API. "name" still communicates that it's used for documentation but also that
it's supposed to be only one or two words that name the value.

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md
File pkg/args/README.md (right):

https://codereview.chromium.org/363083002/diff/1/pkg/args/README.md#newcode212
pkg/args/README.md:212: For non-flag options, you can also provide a help string
for the parameter:
On 2014/07/07 20:37:34, Bob Nystrom wrote:
> On 2014/07/02 19:41:32, nweiz wrote:
> > "help string" -> "name"
> 
> I think I like "help string" here. I want people to understand the name
doesn't
> affect how they access the arg programmatically.

Again, I think "help" is strongly tied to prose descriptions.

[Bob Nystrom, 2014-07-07 23:16:06]

https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md
File pkg/args/CHANGELOG.md (right):

https://codereview.chromium.org/363083002/diff/1/pkg/args/CHANGELOG.md#newcode3
pkg/args/CHANGELOG.md:3: * Options may define `valueHelp` which will then be
shown in the usage.
On 2014/07/07 20:52:00, nweiz wrote:
> On 2014/07/07 20:37:34, Bob Nystrom wrote:
> > On 2014/07/02 19:41:32, nweiz wrote:
> > > "valueHelp" -> "helpValue"
> > > 
> > > I find both of these names confusing though. What do you think about
> > > "valueName"?
> > 
> > I want to include "help" in the name to make it clear that that's what it's
> for
> > and that it doesn't have any other effect. I think "valueHelp" matches
> > "allowedHelp" pretty well.
> 
> "name" still communicates that it's used for documentation

.addOption() already has a parameter called "name" which is definitely not used
just for documentation, so I don't think it conveys that. I want to avoid:

var parser.addOption("foo", name: "bar");
var results = parser.parse(args);
results["bar"]; // User is surprised this doesn't work.

I'm not crazy about "helpValue", but it's the best I could come up with that
makes it clear the parameter doesn't "name" the option in any way outside of
usage.

[Bob Nystrom, 2014-07-07 23:16:23]

Committed patchset #1 manually as r38047 (presubmit successful).