Add a guideline for naming argument features #10509
Conversation
github-actions
bot
added
the
docs ✍️
docs/data-guidelines.md
Outdated
|
|
||
| Sometimes it's useful to represent support for specific arguments of a function or method, as a subfeature of the function itself. To record data about whether a specific argument (parameter) is supported by a function or method, use the following naming conventions: | ||
|
|
||
| - For named arguments, use a subfeature named `argname_argument` with description text `<code>argname</code> argument`. Where _argname_ is the name of the argument as it appears on the corresponding function's MDN page (or specification, if no MDN page is available). |
There was a problem hiding this comment.
I think the most common practice right now is to name the feature after the argument alone (e.g., for hello(firstName, familyName), the feature would be firstName). I was inspired to follow a cue from the _event features here, but I'm not committed to it. (I do think that we should adopt a common description text though.)
docs/data-guidelines.md
Outdated
|
|
||
| - For unnamed arguments, use a subfeature named `ordinal_argument` with description text `ordinal argument` where _ordinal_ is the ordinal number position of the argument. | ||
|
|
||
| For example, to represent support for the second argument of a method `count()`, use a subfeature of `count` named `second_argument` and description text `Second argument`. |
There was a problem hiding this comment.
I'm banking on there being no cases with four arguments. With only three, the lexical sort is fine. With four, it's unordered chaos.
docs/data-guidelines.md
Outdated
|
|
||
| For example, to represent support for the second argument of a method `count()`, use a subfeature of `count` named `second_argument` and description text `Second argument`. | ||
|
|
||
| - For properties of argument objects, use a subfeature named `argname_prop_argument` with description text `<code>argname.prop</code> argument`, where _argname_ is the name of the argument object and _prop_ is the name of the property. |
There was a problem hiding this comment.
Again, this is a bit of a departure from current practice. I don't think do this anywhere yet, but I thought this was nice: it avoids adding an additional nesting layer and ought to sort nicely.
|
Thanks for writing this up! I used "parameter" instead of "argument" whenever I hit this case. |
Ah, right. That's consistent with API reference pages too. I'll update this. |
This was inspired by #9503 (comment) and a general observation that there's no real consensus about how to represent
argumentparameter andargumentparameter objects in BCD. I'm proposing a guideline that addresses this, at least going forward. I'll add a self-review to highlight a couple of details about this.