[process/docs] update lint rule codegen script and lint writing docs

[pq]

The "mechanics" part of writing-lints.md is out of date and tool/rule.dart produces invalid results.

@parlough is your refactoring at a stable enough place that we can update docs and supporting scripts?

[parlough]

@parlough is your refactoring at a stable enough place that we can update docs and supporting scripts?

If https://dart-review.googlesource.com/c/sdk/+/397380 or something similar lands, that should be the last major change. It's ready for review if you have some thoughts on it.

I'd be happy to update both of these, whether or not that change lands.

[pq]

Cool. Thanks! Sorry to be so slow in that PR BTW. I'll add some comments shortly.

[parlough]

Opened cl/407841 to get feedback on an alternative direction.

It still uses the messages.yaml file for as the source of truth for information the docs depend on, but still allows for an class-based implementation that incrementally/optionally use the generated information.

Curious to get everyone's feedback and input. Thanks for taking a look :D

\cc @srawlins

[bwilkerson]

Opened cl/407841 to get feedback on an alternative direction.

Thanks for continuing to push on this.

I think I've heard two concerns with having the implementation of a lint split between two files:

• needing to switch between multiple files in order to update a rule, and
• needing to look in two files in order to see all the information related to a single rule.

I don't see any way to mitigate the first other than to move all the information back out of the messages.yaml file (more on that below). In particular, I don't think the linked change really addresses this concern.

It also doesn't solve the second concern, but it might mitigate it to some extent by reducing the number of files that need to be viewed in order to understand the implementation.

A similar (though not yet available) approach would be to use augmentations rather than mixins. If we had augmentations that might be better, but I haven't spent any time trying to write the code that way so I don't know for sure.

There are two other alternatives that I can think of. I'm not sure I like either one of them, but I'll mention them anyway in case it sparks better ideas.

Code Updater

We could write a generator / updater that would write / update the members of the LintRule that depend on data in the message.yaml file while leaving other members untouched. That would put all of the code related to the implementation back into a single file while still having a place to specify data that isn't needed in production in a way that doesn't use memory.

The biggest disadvantage I can see is that it makes it impossible to see which members are generated. We could mitigate that by adding an annotation on generated members. For example

  @Generated('''
This member is generated and should not be directly edited. To change it update
the `since:` field in the `messages.yaml` file and run the generator
in `tools/update_lints.dart`.
''')
  @override
  /// Stable since Dart 2.10.
  State get state => const State.stable();

Generate messages.yaml

The other idea is to have the LintRule be the source of truth and to generate the message.yaml file from it.

If the only remaining use of the messages.yaml file is the documentation generator (which I think would be the case), then we could argue that we don't need the message.yaml file at all, but I'd at least want us to run the code in the documentation generator that's going to find problems with the way the code in a LintRule is written so that we have some assurance that buggy changes to the linter package can't break the docs we're publishing on the web site.

If sharing code isn't feasible (I don't know whether it is or not) then we'd run the risk of the two copies getting out of sync. Having a way of expressing this data that's less likely to want / need to change (that is, the messages.yaml file) seems like a good idea.

All in all, this feels like it would make the whole system more fragile, but I'm open to arguments showing that it wouldn't be.