dart-lang
Hide implementation of static constants
The Icons class defines icons as IconData constants. This has lead a number of devs to use the implementation (e.g. IconData(57399, fontFamily: 'MaterialIcons')) rather than the interface Icons.airplane. This is a problem because all codepoints (e.g. 57399) change every time the font is updated.
Is there an option or annotation to hide the implementation in docs?
Do you have evidence that developers are copy/pasting from dartdoc rather than from the source (like clicking through in their IDE)?
Can the constructor be made private or @internal so that users are discouraged from using it?
The way this looks now on the top level page, I could see how people might interpret the text string as an example.
What if we moved the value onto the same line as the definition in the template? That might make it more obvious that it isn't intended as an example.
So the first line for a constant would be something like adb_outlined -> const IconData(60984, fontFamily: 'MaterialIcons'), all in the same font/weight.
@srawlins I've lost count but it happens fairly regularly (e.g. https://github.com/flutter/flutter/issues/83208). The IconData constructor can be used legitimately for other purposes (such as with one's own icon font). The @internal annotation is not suitable beause it generates can only be used within its package analysis warnings.
@jcollins-g that would be a slight improvement, but ideally I'd like to completely hide the constants' implentation from the API docs.
Another way to implement this is as a dartdoc tag. Something like @hideImplementations in the enum -- that would enable us to drop that tag in in places where the implementation is uninteresting or even distracting/leading users down the wrong path.
This page turns out to have a lot of traffic in the Flutter docs, so finding a way to reduce misinterpretations here would have a high impact.
Hey, wondering if adding this tag is something I could do? How would I go about that?
Thanks @jcollins-g! I wonder though, since we now rely on the single staticIconProvider annotation (e.g. https://github.com/guidezpl/flutter/blob/constrain-dialogs/packages/flutter/lib/src/material/icons.dart#L152) rather than insert thousands of individual annotations, to achieve the same result?
Thanks @jcollins-g! I wonder though, since we now rely on the single
staticIconProviderannotation (e.g. https://github.com/guidezpl/flutter/blob/constrain-dialogs/packages/flutter/lib/src/material/icons.dart#L152) rather than insert thousands of individual annotations, to achieve the same result?
You shouldn't need thousands of annotations, you should only need a single annotation for the class containing the constants in question.