dart-lang
[doc_imports] Overridding members with no doc comments don't have resolvable references
Overridden members with no doc comment inherit the doc comment of the original member they are overriding.
This is done through Dartdoc, so the analyzer reference resolving doesn't know there's any references to even resolve on the overriding member.
Background:
An example of overridden members and their Dartdocs: DiagnosticableNode<T extends Diagnosticable> overrides emptyBodyDescription from DiagnosticsNode without adding a doc comment.
See: https://api.flutter.dev/flutter/foundation/DiagnosticableNode/emptyBodyDescription.html https://api.flutter.dev/flutter/foundation/DiagnosticsNode/emptyBodyDescription.html
Dartdoc inherits the original doc comment to put on DiagnosticableNode.
If there were references on original doc comment, the analyzer doesn’t know about these references, meaning that it won’t have any resolved references to pass to Dartdoc to use.
Future work
This issue needs to be resolved to allow the usage of @docImports.
We can choose not to make a new, duplicate page/docs for overriding members that have no doc comments. I'm hoping we do that instead. It would also make it less confusing and cut down on pages.
Otherwise, we need another mechanism to resolve these inherited references (and add the doc imports if the references need importing). But having phantom doc imports where you can't even tell why it's there is not ideal.
We already support this behavior in the analysis server for hovers. The analyzer has all the information it needs to allow us to look up the inheritance chain until we find a member with a comment.
