Improve window documentation #9669
Conversation
To reflect Matt Carroll's recent (02/06/2019) email about promoting `WidgetsBinding.instance.window` and demoting `ui.window`. I have to manually search for Matt's email several times when I need to access the Window object. Having it in the documentation would help me do that much faster.
lib/ui/window.dart
Outdated
| /// There is a single Window instance in the system, which you can | ||
| /// obtain from the [window] property. | ||
| /// obtain from `WidgetsBinding.instance.window`, or `window` in `dart:ui` if | ||
| /// `WidgetsBinding` is unavailable. |
There was a problem hiding this comment.
I think we really want to incentivize the use of the singleton though, right? If window is imported directly from dart:ui then that usage cannot be dependency injected, can it? If I'm remembering that right then we should probably use some very strong language to push people towards the binding, if at all possible. What do you think?
There was a problem hiding this comment.
I see below that you elaborated on this. I would suggest including a little bit of the seriousness of the issue in this reference, too.
There was a problem hiding this comment.
I've tried to make it more serious and strong. Please let me know if it looks good, or if you have some sample text that I can follow (or copy/paste) :D
lib/ui/window.dart
Outdated
| /// obtain from `WidgetsBinding.instance.window`. | ||
| /// | ||
| /// There is also a [window] singleton object in `dart:ui` if `WidgetsBinding` | ||
| /// is unavailable. But we strongly advice to avoid statically referencing it. |
There was a problem hiding this comment.
I think this update looks better. Thanks. One last detail, "advice" -> "advise".
To reflect Matt Carroll's recent (02/06/2019) email about promoting
WidgetsBinding.instance.windowand demotingui.window.I have to manually search for Matt's email several times when I need
to access the Window object. Having it in the documentation would
help me do that much faster.