Various issues with the documentation for @protected

[srawlins]

Here is the documentation for @protected. It has several issues:

1. It doesn't address extensions explicitly. Instance members of the on type of an extension can be accessed with an implicit this, but an extension does not extend, implement or mix in the class enclosing such instance members.
2. The docs say the annotation can annotate an "instance member", but then later says the instance member can only be "invoked" from other instance members. Is accessing a field an "invocation"? What about tearing off a method.
3. The docs say that the instance member should only be accessed from "other instance members". What about constructors? It seems that it would make sense to allow a constructor to access such a member.
4. The docs say that the instance member should only be invoked on this (explicitly or implicitly), but it seems that invoking on super would also be perfectly valid.

[lrhn]

Since @protected is only an annotation, it cannot prevent access. It's not a real access barrier, just a statement of intent.

Because of that, I'd probably also allow extension methods to access the protected member on this.
Could consider restricting it to extension members declared in the same library, treating them as part of the same domain.
Because it's useful, not because it's what I'd do if it was a real language feature.

The question is whether the @protected annotation is trying to be its own thing, or to emulate what a real protected declaration might one day look like in Dart (if that ever happens).
If we add that, I'm pretty sure extension methods will not be included.

(It's an access restriction, not a use-case restriction, so tear-offs should work too. Field access is invocations of the corresponding getter/setter. The body of a constructor should count as an instance-member context. Using super. should work too.)

[lrhn]

For the record, the issues for adding a protected feature to the language are dart-lang/language#835, dart-lang/language#3825, or dart-lang/language#757 (and maybe more, there are different possible ways to do that).