Update invalid_case_patterns docs when there's a dart.dev doc link

[MaryaBelanger]

No description provided.

[pq]

@MaryaBelanger: any update here?

[MaryaBelanger]

@pq Not yet, we'd technically need the page merged to the site to provide a link. And that's not going to happen until much closer to the release, if not actually on the release day (the site only documents stable features).

If you need a link ASAP, I could work around that, but it'll be tricky. What I would normally do is create the new page and add the content to it, then hide it from the rest of the site until the release. But in this case, the new content corresponding to this lint is going to be added to the existing content on switch/case, so I can't hide the whole page.

The work around would be creating the new content and adding a note/warning saying "this isn't stable/implemented yet", which can get messy. Also, the new switch content is going to need to point to the new patterns content as well, which also doesn't exist yet.

So... yeah, I guess the question is how urgently do you need to link this lint to the docs? Or when is the cutoff for adding a link to the diagnostic so it'll be there when 3.0 stable releases?

[pq]

Thanks @MaryaBelanger, and no sweat. I think the docs we have are totally sufficient for now and can easily be updated when there's a stable doc to link back to. I'll bump this out of the milestone and we can revisit down the road.

[bwilkerson]

I thought about it a bit, and I don't think we'd even need a cherry pick. We just need to re-publish the docs; the URL will stay the same.

[MaryaBelanger]

Right now, there are links available to a few different places that might provide supporting information to this lint:

• The main patterns page
• The switch section of the main patterns page
• The patterns types page
• The new switch section of the control flow branches page

All of these would just be like "To learn more..." kinds of links.

I see two options:

1. Leave the invalid_case_patterns lint doc as-is. It's long but it works. It's complete and is a good source of info.
2. Break out the longer content (starting here and ending here) into the Patterns types page (and maybe rename the page to something more general like "Patterns reference"). This could mean either:
   • a. Adding a new section about "constant expressions that are now patterns" and placing all this into that section. Benefit being that it's part of the patterns reference.
   • b. Breaking each section (List and map literals, Constant constructor calls, etc.) out into their corresponding sections in Pattern types (List, Map, Constant, etc.)

Thoughts?

[bwilkerson]

I think the first question here is how much information we want to have on the web site about older versions of the language. On the one hand, users can have code that opts out of the 3.0 semantics, so these are situations that they could actually run into. On the other hand, users that are new to Dart likely won't opt out, and having discussions about previous language versions could be distracting. I don't know what the general policy is, but that should factor into the decision.

If we decide that we want to have discussions of older language versions, then I'd be fine having the documentation outside the specific lint rule and referencing it from the description. Do we have a standard format/wording that we want to use for such links? (For example, should they be inlined into the text or called out in a separate section like "See Also"?)

And, of course, these decisions should be made in a way that anticipates where we're heading with unifying the treatment of all of the diagnostic documentation.

[pq]

I lean towards Option 1, maybe w/ a "See also" section with a link or two from the list that @MaryaBelanger added above.

(That said, if either of you felt compelled to restructure the doc more substantially, I'd be up for that too.)

[MaryaBelanger]

I think the first question here is how much information we want to have on the web site about older versions of the language.

Good point, I didn't think of it like that. Generally we want to mention previous functionality as little as possible, which nullifies putting any of this in the docs.

Option 1 it is (leaving this lint alone). As for the "See also...", I like that but I think it's something we should agree that we'll do consistently. It's a minor detail of this conversation we're having, so we can pick it up there once we agree. Thanks everyone!