Should "descriptions" be optional in APIs for keyboard-help content?

[pixelzoom]

My understanding is that alternative input is becoming a standard part of PhET sims, while "descriptions" are not likely to be fleshed out for some time. So would it make more sense to make descriptions optional in the API?

Most (all?) of the API for creating keyboard-help content treats descriptions as required. They are required parameters to functions. Examples that I encountered while working on phetsims/geometric-optics#281 include:

• KeyboardHelpSection.labelWithIcon
• KeyboardHelpSection.labelWithIconList
• KeyboardHelpSection.createJumpKeyRow

So I'm finding myself having to decide whether to pass the empty string '' to API calls, or create dummy descriptions in the strings.json file. The latter seems preferrable, but is an additional (and significant) cost.

[zepumph]

Yes that is a correct summary. It should be an option. Our goal was to limit the confusion description. I'll see how many usages there are and try to take care of them, if its too much for today I may give up though.

[zepumph]

labelWithIconList is complete. It took longer than I would like, but I kinda feel too in it now. I'll keep going.

[pixelzoom]

I said:

So I'm finding myself having to decide whether to pass the empty string '' to API calls, or create dummy descriptions in the strings.json file. The latter seems preferrable, but is an additional (and significant) cost.

Now that descriptions will be optional, I'd prefer to remove those options from my sims that don't have descriptions (fourier, geometric-optics), and remove the placeholders from the strings.json file. Does that seem reasonable @zepumph?

[zepumph]

Whatever you would prefer, but will you please wait for my refactor to complete?

[pixelzoom]

Yes, I'll wait for this issue to be closed.

[zepumph]

Alright. labelInnerContent is now an option. There were many helper functions that used the primary labelWithIcon function, so there were a fair number of functions changed in KeyboardHelpSection (along with their usages). local fuzzing is passing.

@pixelzoom, can you please review. Does this feel like a better API to you?

@pixelzoom, where you passed '', I just removed it, where you created a full dummy string, it is over to you.

[pixelzoom]

This is a much nicer API, and a better match for PhET's current "alt input now, descriptions later" approach.

In the above commits, I removed the description placeholders from geometric-optics and fourier-making-waves.

Closing.