Expand on mixin class

[MaryaBelanger]

Fixes #4826

I had trouble making the connection between what the on clause is for and how using abstract provides the same benefit. Here's what I think the reason is (added to mixins.md), but I could be off:

By declaring Musician abstract, you force any type that uses
it to define the abstract method its behavior depends on.

This is similar to how the on directive ensures a mixin has access to any
interfaces it depends on by specifying the superclass of that interface.

*Also not sure if I'mm using "interfaces" correctly there.

I assumed that this would be a common use case, so I put this explanation in its own subsection on the mixin page, "abstract mixin class".

[github-actions]

Visit the preview URL for this PR (updated for commit 01c9f4b):

https://dart-dev--pr4834-class-modifiers-2-4nrn8v3y.web.app

_{(expires Thu, 18 May 2023 21:06:16 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: d851bc446d3c4d7394c5406c6f07255afc7075f3}

[MaryaBelanger]

This is pointing at v3.0 but if it can't get reviewed before merging that into main tomorrow morning, it'll be fine to merge this directly into main later on.

[munificent]

on clauses are really confusing. Fortunately, almost no one actually needs to use them.

People often think they are used to specify the methods than a mixin can call on itself and then get implemented by the thing that applies the mixin. That's what your example is about here.

But you don't need an on clause for that at all. As you do here, you can just make the type abstract and define abstract methods. Another way to accomplish something similar is to put an implements clause on the mixin or mixin class and then not actually implement the interface.

The only time you need an on clause is when the mixin wants to do super calls. It specifies the interface that those are resolved against. So in:

mixin M {}

class B {}
class C extends B with M {}

If there's some method in C that you want to be able to call from M, you can just declare it abstract in M and call it, like in your example:

mixin M {
  void c(); // Declare abstract.
  void test() {
    c();
  }
}

class B {}
class C extends B with M {
  void c() { ... }
}

You need an on clause if M wants to have a super call that needs to be resolved against B in the example here:

abstract class BStuff {
  void b();
}

mixin M on BInterface {
  void test() {
    super.b();
  }
}

class B {
  void b() { ... }
}

class C extends B with M {}

Honestly, on clauses and super calls in mixins are just not a great feature. Almost any time you think you need one, there's probably a better design you should use instead. But Flutter used super calls in a couple of key mixins early on (because the VM allowed it even though the language didn't specify it), so we were sort of forced to turn it into a real feature. But I definitely wouldn't emphasize it in the tour since it tends to confuse users and it's rarely what they want.

[munificent]

Summarizing: I think your example is OK here, but I wouldn't mention it in the context of on clauses. If that makes the entire example not worth keeping, I think it's fine to eliminate this section.

[brianquinlan]

The text before this section contains these sentences:

Sometimes you might want to restrict the types that can use a mixin.
For example, the mixin might depend on being able to invoke a method
that the mixin doesn't define.

That is confusing given what you just said. There might not be time for this but it might make sense to reorder this page i.e. have an example of calling the mixing classes method from the mixin near the top (where the on example currently is), then have a section about class mixin and then finally a section explaining on with the "you will almost certainly never need" caveat and an explanation that it is only useful for super calls.

[MaryaBelanger]

Hmm.. ok, I think what I'll do for now is keep the new section referencing similarity to using on, but more of an aside than the purpose statement it currently is. Like Brian said, this is a direct response to the earlier text describing on.

Later* I'll rewrite the section to take out any emphasis on on and instead describe the same example for both mixins and mixin classes simply as "the use case where you want to require that whatever uses the mixin specifies some methods".

*Only delaying it because, again like Brian said, I think it'd be best to rearrange the page, since ...

• this isn't just a use case for mixin classes,
• and, like Bob said, the existing description of on for regular mixins seems misrepresented and could probably use a rewrite

And doing that will take a bit of attention that I won't have before publishing the new pages. I'd like to include this info on the first publish. @munificent if you think the content just absolutely shouldn't be published, please let me know!

[atsansone]

My two cents: It's worth mentioning in passing for coverage. It should be reviewed in the next week or so to see if it's truly relevant. I'm a fan of being opinionated in docs, even if the opinion is to skip something entirely.

[parlough]

I pulled out the sealed changes in #4847 so I could land those and other fixes and so discussion can continue on mixins here.

[parlough]

I've changed the base branch to main since the v3.0 branch landed in main.

[MaryaBelanger]

@atsansone could you approve this to get the information out for now, so I can come back and apply Bob's concerns later on?

[atsansone]

One issue, otherwise LGTM. No need for a second pass.

[atsansone]

My two cents: It's worth mentioning in passing for coverage. It should be reviewed in the next week or so to see if it's truly relevant. I'm a fan of being opinionated in docs, even if the opinion is to skip something entirely.