Docs: Establish preference for objects over strings in rule options

[JoshuaKGoldberg]

Before You File a Documentation Request Please Confirm You Have Done The Following...

• I have looked for existing open or closed documentation requests that match my proposal.
• I have read the FAQ and my problem is not listed.

Suggested Changes

Following up on a couple of threads:

• feat(eslint-plugin): [consistent-generic-constructors] add rule #4924 (comment)
• feat(eslint-plugin): [consistent-generic-constructors] add rule #4924 (comment)

I feel moderately strongly that we should standardize on always using the object in new rules. It's more self-documenting and is the format most rules end up using as they gain more options.

Affected URL(s)

https://github.com/typescript-eslint/typescript-eslint/blob/main/CONTRIBUTING.md

[Josh-Cena]

I still hold my dissent. Think about function calls:

parseCode(code, { failfast: true });

We can refactor that into parseCode({ code, failfast: true }), but do we want to?

Differentiating between a primary option and a secondary option highlights the former's importance. The primary option isn't just any option: it determines the entire behavior of the rule. Having "consistent-generic-constructors": ["error", "type-annotation"] is synonymous to "parameter-properties": ["error", "always"]—if we change the primary option, the rule's reports will be completely inverted. This should not happen with secondary options, which refine the existing reports (e.g. check more positions, or ignore some cases).

Rules that have a primary option are, really, two rules smashed together, with a string option to toggle between two modes. For example, we can imagine splitting consistent-generic-constructors into prefer-constructor-type-arguments and no-constructor-type-arguments, with completely opposite reports. The only reason we are not doing that is because this is against ESLint's API design norms of "don't have opposing rules".