Linter: Update lint docs to call out associated Effective Dart rules

[pq]

Some were done, others weren't. New rules have come and some links have been updated. Net-net: it'd be great to do an audit and cleanup.

See also: https://github.com/dart-lang/site-www/issues/921

[a14n]

I started to have a look yesterday and PRs will come :)

I have concerns about how to keep lint description/details up to date with the description of the style guide ? Should we:

• copy/paste manually
• only have a link from lint description to site
• have a script to automatically copy description/details from the site to the linter description.

I like the last option. I will try to prototype it.

[a14n]

• have a script to automatically copy description/details from the site to the linter description. I like the last option.

I will try to prototype it.

After looking at some rules I'm not sure it's a good idea.

[chalin]

For a while now I've been thinking about how to use our code excerpt tooling to automate doc updates like these. If you might be interested, let me know and I'll provide you with details.

[pq]

@chalin: yes please! I'd be very curious for details.

[chalin]

Can you give me an example of the kind of description/details that you'd like to extract?

[a14n]

For instance here is the detail/descriptions for https://www.dartlang.org/guides/language/effective-dart/style#do-name-types-using-uppercamelcase

https://github.com/dart-lang/linter/blob/e1a6c5edf96c1cab1e54775ba9e02e45d4413410/lib/src/rules/camel_case_types.dart#L10-L34

[a14n]

It could be fine to replace desc and details with the content of the site (without the note section and with some transformations for GOOD/BAD sections)

[bwilkerson]

have a script to automatically copy description/details from the site to the linter description.

That seems like a bad idea. The comments reflect what the lint is actually doing, rather than what the style guide says ought to happen. If we had a tool to identify when the two diverge then we'd have an easy way to track changes to the guide, but I don't know that it's worth doing. But we definitely shouldn't auto update the description so that the description doesn't match the code.

[chalin]

That works for me. So we're going with a one-way correspondence from the Effective Dart page(s), referring to appropriate lint rule(s)?

[pq]

That works for me. So we're going with a one-way correspondence from the Effective Dart page(s), referring to appropriate lint rule(s)?

Lint rules derived from Effective Dart should point back to it too. (For attribution and added context.)

[pq]

https://github.com/dart-lang/site-www/issues/921 implements the other direction (links from the Effective Dart docs). Cheers @kwalrath ! 🥇

Next up there's talk of capturing these associations in a separate file that we can process to generate back links in the linter docs...