Stabilise functional support for message option

[ybiquitous]

Currently, many built-in rules support the message option's function feature:

stylelint/docs/user-guide/configure.md

Lines 114 to 137 in 113888c

	Experimental feature: some rules support message arguments. For example, when configuring the `color-no-hex` rule, the hex color can be used in the message string:
	`.stylelintrc.js`:
	```js
	{
	'color-no-hex': [true, {
	message: (hex) => `Don't use hex colors like "${hex}"`,
	}]
	}
	```
	`.stylelintrc.json`:
	<!-- prettier-ignore -->
	```json
	{
	"color-no-hex": [true, {
	"message": "Don't use hex colors like \"%s\""
	}]
	}
	```
	With formats that don't support a function like JSON, you can use a `printf`-like format (e.g., `%s`). On the other hand, with JS format, you can use both a `printf`-like format and a function.

Rough calculation:

$ git grep -l 'messageArgs: \[' lib/rules/*/index.js | wc -l
      92

And people have never complained about the feature spec, as I remember.

So, I suggest dropping experimental from this feature and officially publishing it.

Here're tasks:

• Add the function support to all rules except for deprecated ones.
• Fix the test:

  • stylelint/lib/rules/__tests__/index.test.js

    Lines 62 to 63 in 113888c

    	// NOTE: If all rules support a custom message option, we should remove this `if` statement.
    	if (!jsCode.includes('\tmessageArgs: [')) return;

• Remove the sentence from all the rule README:

  • stylelint/lib/rules/alpha-value-notation/README.md

    Line 14 in 113888c

    The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.

• Remove "Experimental feature" wording from the doc:

  • stylelint/docs/user-guide/configure.md

    Line 114 in 113888c

    Experimental feature: some rules support message arguments. For example, when configuring the `color-no-hex` rule, the hex color can be used in the message string:

[jeddy3]

SGTM.

[mattxwang]

I'm doing this work now! I have a handful of cases that I'm not exactly sure how to proceed:

• for rules like block-no-empty, there is no set of arguments to pass to the message (it doesn't reference any elements). Should I:
  • make the error message a parameterless (constant) function, and then pass an empty [] into messageArgs? The pro here is that we consistently use the same method to create custom messages, but it feels a bit strange/potentially inefficient.
  • not add messageArgs?
  • something else?
• for rules like color-named, the expected and rejected functions have different numbers of arguments. Should I:
  • just have different input lengths in messageArgs
  • create a falsy parameter so that messageArgs always has the same number of elements (or standardize the functions to throw away an argument, etc.)
  • something else?

In #7194, I have included demos of:

• making no-argument message functions constant (see: block-no-empty)
• proceeding to have variable-length functions when the expected/rejected disagree with each other (see: color-named)

I may also be missing some context (I've read through #4117, #6312, #6589 but may have missed something). Let me know what we think!

[mattxwang]

Separately, I may have missed: is there a specific way we're documenting the order and meaning of arguments for each message function?

[ybiquitous]

make the error message a parameterless (constant) function, and then pass an empty [] into messageArgs? The pro here is that we consistently use the same method to create custom messages, but it feels a bit strange/potentially inefficient.

I have no strong opinion about that, but I feel passing messageArgs: [] is a bit verbose, even if doing so is consistent.

the expected and rejected functions have different numbers of arguments

I think it's OK to pass different messageArgs for the each function.

is there a specific way we're documenting the order and meaning of arguments for each message function?

For now, I don't find a good way to document them. I believe we can avoid documenting if no idea, although it's the best ideally.

[mattxwang]

Thanks for the quick response! For now, I can:

• pass different messageArgs
• hold on if others have opinions about messageArgs: []
• not document them for now

I could also do a documentation pass in another PR. One thought is perhaps we can autogenerate the documentation from examples and/or the source code?

[github-actions]

This issue is older than one month. Please ask before opening a pull request, as it may no longer be relevant.