Site-www: Add lint names aside style rules?

[chalin]

_From @a14n on June 13, 2018 6:4_

In the style guide it could be worth to advertise the linter name that can be used to ensure the rule is enforced.
WDYT? /cc @pq @munificent

_Copied from original issue: dart-lang/site-webdev#1641_

[pq]

Sound like a great idea to me! 👍

[munificent]

👍 though I probably won't have time to do this. I'm trying to take a break from "Effective Dart" to focus on other stuff for a while.

[pq]

@a14n: happy to help either here or on the linter side. Just let me know. 👍

[a14n]

To start we need a kind of template how to display a lint rule in a rule section on the site.

For instance we could start with DO name types using UpperCamelCase that should advertise the linter rule camel_case_types.

NB: it could be worth to have a template that can display more than one linter name for a given rule.

[chalin]

@a14n - I don't know how many rules would be involved, but if you are working on this, would you mind sharing a (layout) design prototype so that we can tune it before full adoption? Maybe for a section with one rule and a section with more than one rule. (I have some design ideas but I can't be focusing on this atm.)

[a14n]

I don't have a good idea of what could be the layout design.

A note paragraph (_You can ensure this rule by enabling the linter rule xxxx_) at the end of the rule's section is clear but could be a little redundant if all sections have this paragraph.

[kwalrath]

Starting on this now.

[kwalrath]

I'm thinking of something like this:

We could always make it prettier later. It's staged at https://kw-staging-dartlang-2.firebaseapp.com/guides/language/effective-dart/style#do-name-types-using-uppercamelcase. (Definitely not done yet!)

[a14n]

It looks great!

[pq]

Awesome. I say ship it. 👍

Something that would be useful for us on the linter would be a way to extract these correspondences programmatically. I could use that to generate (and then validate) back-pointers from the linter docs, create an options file that defines them all (currently maintained manually), and for creating a kind of scorecard (a la what we've been exploring in https://github.com/dart-lang/linter/issues/1365).

@kwalrath : how crazy would that be? Can we add metadata to the markdown? Alternatively, is it structured enough that I could safely infer structure?

[kwalrath]

Yes, I'd love for this to be automatically extractable. I think we should be able to add metadata to the markdown on our site. Another possibility is to maintain a spreadsheet of links and linter rules, and have automated testing on both site-www and linter for those.

A benefit of the spreadsheet approach would be the ability to add other columns, like for rules that combine other rules, or for docs outside of Effective Dart (e.g. for Flutter rules).

[pq]

A benefit of the spreadsheet approach would be the ability to add other columns, like for rules that combine other rules, or for docs outside of Effective Dart (e.g. for Flutter rules).

Great points. I'm sold! Happy to drive on the linter side. Needless to say, happy to pitch in on putting the table together too.

Thanks!