Comments (4)
I think we should support referencing the members of the aliased type. It seems sensible, given someone wants to document a type alias.
from sdk.
I'd say "no". The rule I use to understand what's in scope is that it's what's in scope inside the commented declaration (where "in scope" really means "can be referenced by a raw identifier" rather than the actual lexical scope).
The members of the aliased type is not in scope "inside" the type alias.
That said, aliases that allow static member access could be considered "special", and provide access to at least those static members. Could say that they give access to the instance members too, for good measure. But it's because they're special, not because it's obvious.
from sdk.
As a concrete example, if we wanted to keep a doc comment on SetMixin and refer to members of SetBase
(the aliased type), like add
and length
, should they just be written as [SetBase.add]
and [SetBase.length]
? (They would appear at api.dart.dev with that qualified name, 'SetBase.add' and 'SetBase.length'.)
from sdk.
The language specification unambiguously defines the current scope for a documentation comment:
Documentation comments are comments that begin with the tokens
///
or/**
. Documentation comments are intended to be processed by a tool that produces human readable documentation. The current scope for a documentation comment immediately preceding the declaration of a classC
is the body scope ofC
. The current scope for a documentation comment immediately preceding the declaration of a non-redirecting generative constructork
with initializing formals is the formal parameter initializer scope ofk
. Otherwise, the current scope for a documentation comment immediately preceding the declaration of a functionf
is the formal parameter scope off
.
This basically implies that a documentation comment on a class can "see" the members declared in the body of that class, the formal type parameters of the class, if any, and anything in the enclosing library scope (including imported stuff).
We should probably make this specification slightly more detailed and say that it is possible to refer to an identifier id
in this documentation comment if it can be resolved using lexical lookup (as defined in the section 'Lexical Lookup'), such that we have access to members of the interface of the class that are inherited from the superclass or "promised" by the implements
clause, not just the members that are declared in the class itself.
However, it is not obvious to me that the relevant references in the documentation of a declaration are exactly the ones that are the result of resolving an identifier in the body of said declaration, even with that clarification about this.id
.
You could also say that the members of the interface of a type are relevant to the documentation of a declaration that introduces said type into the enclosing scope. Some declarations introducing a type will also have formal type parameters, and they'd be relevant as well.
I think this means "no change" to the current behavior, except that members of a type which is aliased in a typedef
should be available as well. (But there could be additional type-introducing declarations in the future).
An obvious corner case to consider would be typedef F<X extends Widget> = X;
which would consider the members of F
to be the members of Widget
, ignoring the fact that F<MySpecialWidget>
has a different set of members (some members in addition to the ones that Widget
has, and some members shared by both, but with different signatures).
I think it would make sense to generalize the rules about documentation comments along these lines. Presumably, it would be a non-breaking change.
from sdk.
Related Issues (20)
- [vm/core] Inlining `_GrowableList.add` bloats program too much HOT 2
- vm/dart/isolates/shared_primitives_test changing from flaky to RTE on vm-reload-linux-debug-x64 HOT 2
- [diagnostic] don't report `DUPLICATE_FIELD_NAME` if the name is invalid
- Quick fix to convert params/args between positional and named HOT 2
- Analyzer exception doesn't specify affected file HOT 2
- VM always prints "<isolate> has no debugger is attached and is paused"
- [dart2wasm] UnimplementedError when calling Flutter's Matrix4.translate with an integer argument
- `where` can't accept an async predicate HOT 5
- [Augmentations] Wrong error in the analyzer when augmenting enum member
- [Augmentations] No error in the analyzer when augmenting a function type with no augmented type
- [Augmentations] No error in analyzer for mixin and extension when augmentation is before original declaration HOT 1
- [Augmentations] Analyzer crash on co19/LanguageFeatures/Augmentation-libraries/augmenting_types_A01_t01
- [Augmentations] Analyzer error when augmenting representation variable
- [Augmentations] Omitted type bound is not inherited
- [Augmentations] No error in the analyzer if augmentation declares a different return type HOT 2
- The integer negative zero formats as "-0.0" HOT 5
- [dart2js] bug in global inference with `call` getter HOT 1
- DevTools URI opens to a white screen
- Isolate.run error run with closure HOT 1
- LateInitializationError in ResolutionVisitor.visitForEachPartsWithPattern in resolution_visitor.dart
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from sdk.