Update documentation to cover non-function type aliases

[leafpetersen]

This issue tracks support of the non-function type alias feature. See the enclosing meta-issue for details.

@kwalrath @davidmorgan do you want separate issues for internal/external docs? Who else should I loop in here?

cc @franklinyow @mit-mit

[davidmorgan]

We don't have any internal documentation about general language features--except for null safety. So I think there's nothing to do for internal documentation.Thanks.

[mit-mit]

For external docs, I think we need to update https://dart.dev/guides/language/language-tour#typedefs

[eernstg]

@kwalrath, perhaps we should communicate a bit about this?

The text in https://dart.dev/guides/language/language-tour#typedefs needs a few updates, and then an extension:

At first, we should be a bit more general now that a type alias can define an alias for any type, not just a function type. Maybe we could do something like the following:

A typedef, or function-type alias, gives a function type a name that you
can use when declaring fields and return types. A typedef retains type
information when a function type is assigned to a variable.

-->

A type alias, which is declared by a declaration starting with the keyword typedef, gives
a type a name that you can use as a type, e.g., when declaring fields and return types.
A type alias can have type parameters. A type alias can be convenient because it is more
concise than the type that it denotes. Also, a type alias with type parameters can remove
even more verbosity, and ensure consistency, if it uses the same type parameter more
than once.

typedef ListMapper<X> = Map<X, List<X>>;
Map<StatelessWidget, List<StatelessWidget>> m1; // Verbose.
ListMapper<StatelessWidget> m2; // Same thing, less verbose, less redundant.

We may be able to reuse the old example using Function, but it's not very relevant (the description assumes that there is no other way to write the precise function type, but we can do that inline today: int Function(Object, Object)).

[mit-mit]

I'd love to start with a simple example, like:

typedef IntList = List<int>;
IntList il = [1,2,3];

[leafpetersen]

@kwalrath any updates?

[kwalrath]

This won't be in a stable release for a while, correct? We often don't cover features until they're in a stable release (with the exception of features where we want feedback or that need a lot of work for our readers to incorporate).

[franklinyow]

@kwalrath This is targeting the next dart stable release

[leafpetersen]

@kwalrath @mit-mit we should add the 2.13 features to this as well.

[leafpetersen]

@kwalrath Any concerns about this being ready for when we hit stable?

[kwalrath]

@kwalrath Any concerns about this being ready for when we hit stable?

Nope

[franklinyow]

Moving this to April

[franklinyow]

@kwalrath Any update on this doc?

[kwalrath]

We expect to have the docs for stable, not beta.

[franklinyow]

@kwalrath I'm moving this to June

[kwalrath]

I'd love to start with a simple example, like:

typedef IntList = List<int>;
IntList il = [1,2,3];

@mit-mit we'd talked about maybe using JsonMap instead. Did you find that example?

[franklinyow]

Link to site-www
dart-lang/site-www#2937

[franklinyow]

closing as dart-lang/site-www#2937 is closed