Sdk: Documentation should explain new typedef syntax better
I've helped two different people in the past few days who were confused about how to convert the old typedef syntax to the new typedef syntax (and how to use it for generic function types):
// Old syntax
typedef T MyFunctionType<T>(T x, String y);
// New syntax
typedef MyFunctionType<T> = T Function(T, String);
//New generic function type syntax
typedef MyGenericFunctionType = T Function<T>(T, String);
This doesn't seem to be covered much here:
https://www.dartlang.org/guides/language/language-tour#typedefs
It would be great to have some more detailed guidance on this to point people to.
cc @sethladd @kevmoo @apwilson
leafpetersen
All 20 comments
CC @kwalrath – likely better to track this on site-www – not much to do in the repo here, right? (other than the spec)
kevmoo
on 18 May 2018
We might also want to take advantage of the opportunity to let users know that there is a quick assist in server that will automatically translate from the old syntax to the new syntax.
bwilkerson
on 18 May 2018
Is this mainly a 1.x -> 2 conversion issue? If so, the place for help on that is not the language tour, but the Dart 2 page or a page that it points to, such as Fixing Common Type Problems.
Do you know what symptoms they were seeing that made them do this change? I'm wondering if we should add more to the Problems section A function of type ... can't be assigned.
kwalrath
on 18 May 2018
Is this mainly a 1.x -> 2 conversion issue?
Yes and no. This is a new feature in Dart 2. You can still use the old syntax, but people are being encouraged, in part by lints, to use the new feature.
If so, the place for help on that is not the language tour,
The language tour has an entry for typedefs which uses the old syntax, and then mentions the new syntax (but only the "generic function type" version). It seems like it would be better to either uniformly use the new feature, or perhaps show the old feature and its replacement version (as well as the new functionality available).
Fixing Common Type Problems.
It's not quite a type problem, but it could be worth an entry there.
Do you know what symptoms they were seeing that made them do this change?
No problem, they were just encouraged (again, I think by a lint, @apwilson can you confirm?) to use the new syntax and were having trouble doing so. Or in @kevmoo's case, he actually wanted the new generic function type syntax.
In one case, the programmer was migrating code that looked like:
typedef T Foo<T>(T x);
and accidentally wrote:
typedef Foo<T> = Function<T>(T x);
instead of
typedef Foo<T> = Function(T x);
In the second case, the programmer actually wanted a generic function type:
typedef Foo = Function<T>(T x);
but again accidentally wrote:
typedef Foo<T> = Function<T>(T x);
The fact that you can put a <T> in either (or both) positions (but for different purposes) is confusing, and seems worth explaining.
leafpetersen
on 19 May 2018
@bwilkerson what's a good example of using the quick assist? Is this something you can do in all IDEs that have Dart support?
kwalrath
on 19 May 2018
Yes, the lints indicated we should use the new syntax.
On Fri, May 18, 2018, 4:02 PM Kathy Walrath notifications@github.com
wrote:
@bwilkerson https://github.com/bwilkerson what's a good example of
using the quick assist? Is this something all IDEs with Dart support
support?—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/dart-lang/sdk/issues/33165#issuecomment-390353938,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAIuGhrYIIlRQqgoNnLI4ktdlM2X9mx5ks5tz1L3gaJpZM4UFO9Q
.
apwilson
on 19 May 2018
what's a good example of using the quick assist?
The examples that Leaf has given are all good. The assist currently doesn't erase variable names (as Leaf did), but we can change that if we think that was the wrong decision.
Just paste any of the old syntax examples and click on "typedef". In IntelliJ you should get a yellow lightbulb icon next to the right edge of the editor that has a drop-down menu containing the suggestion to convert it to the new syntax (I don't remember the actual wording).
If you find any examples that produce different results than what Leaf suggested, we should look at them to make sure it isn't a bug in server.
Is this something you can do in all IDEs that have Dart support?
Yes.
bwilkerson
on 19 May 2018
The language tour has an entry for typedefs which uses the old syntax, and then mentions the new syntax (but only the "generic function type" version). It seems like it would be better to either uniformly use the new feature, ...
- [x] Done, as of https://github.com/dart-lang/site-www/pull/923.
or perhaps show the old feature and its replacement version
- [x] Done in Effective Dart: DON’T use the legacy typedef syntax.
The fact that you can put a
<T>in either (or both) positions (but for different purposes) is confusing, and seems worth explaining.
I agree, but Bob (@munificent) had this to say about that:
The generic function type use case is vanishingly rare. (I don't recall ever seeing one in the wild, nor do I know of any real-world use cases that motivated adding it to the language.) I don't think it's worth putting in "Effective Dart".
- [ ] Maybe @munificent @kevmoo and @leafpetersen can discuss this offline and post here the final decision? We can then update the docs, or agree not to :)
We might also want to take advantage of the opportunity to let users know that there is a quick assist in server that will automatically translate from the old syntax to the new syntax.
Quick assists are great, but I don't think that site-www is the place to document them IMHO.
chalin
on 14 Jun 2018
I forgot one more thing: if writing the following by accident occurs often enough, then maybe we need a lint rule for it (/cc @pq):
typedef Foo<T> = Function<T>(T x);
Maybe we need a lint to complain about unused type parameters, as in this case too:
typedef Foo<T> = Function();
If we feel that having such lint rule(s) makes sense, then I'll open an issue over the linter.
chalin
on 14 Jun 2018
if writing the following by accident occurs often enough, then maybe we need a lint rule for it (/cc @pq):
...
Maybe we need a lint to complain about unused type parameters, as in this case too:
Both SGTM!
leafpetersen
on 14 Jun 2018
Why isn't this just a warning in the language, similar to an unused variable or method?
AFAIK @pq (and others) desire that _unused_ code is detected by the analyzer, not the linter.
matanlurey
on 14 Jun 2018
Why isn't this just a warning in the language, similar to an unused variable or method?
These are not language warnings. The analyzer gives hints on these sometimes, but that's basically in the same category as lints.
leafpetersen
on 14 Jun 2018
Correct, sorry, I still don't understand the different diagnostic levels.
matanlurey
on 14 Jun 2018
Linter issue: https://github.com/dart-lang/linter/issues/1027
@leafpetersen - can we close this issue now?
chalin
on 14 Jun 2018
... or do you still want to discuss the "generic function type use case" mentioned above?
chalin
on 14 Jun 2018
The generic function type use case is vanishingly rare. (I don't recall ever seeing one in the wild, nor do I know of any real-world use cases that motivated adding it to the language.) I don't think it's worth putting in "Effective Dart".
I'm not sure about Effective Dart, but there are most definitely uses of this in the wild already. See for example mockito. We need to document this feature somewhere. If this isn't the place, then where is the right place?
leafpetersen
on 14 Jun 2018
where is the right place?
The Language Tour. @kwalrath WDYT?
chalin
on 14 Jun 2018
The language tour is not complete. As its first sentence says, it "shows you how to use each major Dart feature." It shouldn't cover features that most people aren't likely to use.
I think we need another (non-spec) place for those less-used corners of the language. Maybe it could be an "Advanced Language Features" page (/guides/language/advanced). It might not explain everything completely, but it could list features, maybe have short examples, and point to more information if it's available.
The "more information" places could be blog posts, @dartlang.org posts, Medium posts, code in a stable repo, ...
An alternative to creating an Advanced Language Features page would be to create a complete page, Dart Language Features, which would point everywhere (including the language tour). That would be harder, though.
What do you think, @leafpetersen & @chalin?
kwalrath
on 14 Jun 2018
Generally, I'd agree with your suggestions, but in this case I don't think that we are dealing with an advanced feature, and I think that it can be relatively concisely explained. How about this: I'll put together a short update to the Language Tour typedef section, and then we can see whether it fits there or not?
chalin
on 14 Jun 2018
@kwalrath I think the language tour should at least point out that there is a difference and where to read more about it (if it is not explained directly).
zoechi
on 15 Jun 2018
Related issues
Hixie
·
3Comments
emilniklas
·
3Comments
55555Mohit55555
·
3Comments
DartBot
·
3Comments
ranquild
·
3Comments
Most helpful comment
@kwalrath I think the language tour should at least point out that there is a difference and where to read more about it (if it is not explained directly).