carbon-design-system / carbon-components-svelte

Svelte implementation of the Carbon Design System
https://svelte.carbondesignsystem.com
Apache License 2.0
2.68k stars 261 forks source link

Alphabetize prop names in documentation #1891

Closed theetrain closed 8 months ago

theetrain commented 8 months ago

This is blocked by #1629

In the component docs, the API section will render prop names in the order they're defined.

SimpleProgrammingAU commented 8 months ago

I alphabetised them in code to make the editing experience easier. This is something I'm gonna want to do before doing the tasks for #1629. Is there a way we can make this an initial step for #1629 without it becoming too painful?

metonym commented 8 months ago

I'm opposed to this. Props are purposefully listed with the most relevant/important. In the docs, reactive vars are listed first.

Generally, props should be sorted by importance, relevance, then grouped by similarity.

metonym commented 8 months ago

For example - yes, it's easier to initially find a prop in an alphabetized list, but it's inefficient beyond that.

A prop like hideLabel naturally follows labelText. If alphabetized, hideLabel would appear before labelText.

Props like invalidText and warnText should also be close in proximity.

theetrain commented 8 months ago

@metonym fair enough, the rationale is sound. Seeing most-used props first does provide good quality of life to users, myself included. I don't see a way to ensure this ordering via linting or docs generation, but that's ok.

theetrain commented 8 months ago

I added a "Prop ordering" rule in https://github.com/carbon-design-system/carbon-components-svelte/issues/1621 so that this is captured somewhere. We can continue to discuss ordering in that proposal.