Repository navigation
Hide implementation of static constants #2657
Description
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?
Activity
srawlins commentedon May 25, 2021
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
@internalso that users are discouraged from using it?jcollins-g commentedon May 25, 2021
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.
jcollins-g commentedon May 25, 2021
So the first line for a constant would be something like
adb_outlined -> const IconData(60984, fontFamily: 'MaterialIcons'), all in the same font/weight.guidezpl commentedon May 26, 2021
@srawlins I've lost count but it happens fairly regularly (e.g. flutter/flutter#83208). The
IconDataconstructor can be used legitimately for other purposes (such as with one's own icon font). The@internalannotation is not suitable beause it generatescan only be used within its packageanalysis warnings.@jcollins-g that would be a slight improvement, but ideally I'd like to completely hide the constants' implentation from the API docs.
jcollins-g commentedon Jun 2, 2021
Another way to implement this is as a dartdoc tag. Something like
@hideImplementationsin 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.guidezpl commentedon Jun 3, 2021
That would be ideal!
jcollins-g commentedon Aug 30, 2021
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.
guidezpl commentedon Nov 5, 2021
Hey, wondering if adding this tag is something I could do? How would I go about that?
guidezpl commentedon May 23, 2022
sorry to ask, but "any updates?"
srawlins commentedon Aug 4, 2022
Sorry, no updates.
guidezpl commentedon May 4, 2023
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?jcollins-g commentedon Jun 2, 2023
You shouldn't need thousands of annotations, you should only need a single annotation for the class containing the constants in question.
guidezpl commentedon Jun 2, 2023
You're right, I don't know where I got that idea (:
Update flutter to dartdoc 6.3.0 and hide Icons implementation from do…
Update flutter to dartdoc 6.3.0 and hide Icons implementation from do…