[proposal] add an `@unstableGetter` annotation #53632

pq · 2023-09-27T17:37:00Z

More context in #59313.

@eernstg: word-smithing welcome!

pq · 2023-09-27T17:43:05Z

Here's a sample of an existing annotation that informs a lint. (@eernstg: it should look familiar as IIRC you helped write it!)

/// Annotation for intentionally loosening restrictions on subtyping that would
/// otherwise cause lint warnings to be produced by the `implicit_reopen` lint.
///
/// Indicates that the annotated class, mixin, or mixin class declaration
/// intentionally allows subtypes outside the library to implement it, or extend
/// it, or mix it in, even though it has some superinterfaces whose restrictions
/// prevent inheritance.
///
/// A class, mixin, or mixin class declaration prevents inheritance if:
///
/// * it is marked `interface` or `final`
/// * it is marked `sealed`, and is implicitly `interface` or `final`
///   based on the modifiers of its superinterfaces
/// * it is an anonymous mixin application, and is implicitly `interface` or
///   `final` based on the modifiers of its superinterfaces
///
/// A declaration annotated with `@reopen` will suppress warnings from the
/// [`implicit_reopen`](https://dart.dev/tools/linter-rules/implicit_reopen)
/// lint. That lint will otherwise warn when a subtype has restrictions that are
/// not sufficient to enforce the restrictions declared by class modifiers on
/// one or more superinterfaces.
///
/// In addition, tools, such as the analyzer, can provide feedback if
///
/// * The annotation is applied to anything other than a class, mixin, or mixin
///   class.
/// * The annotation is applied to a class or mixin which does not require it.
///   (The intent to reopen was not satisfied.)

parlough · 2023-09-28T00:16:07Z

I guess my concern is not necessarily future conflicts but being accidentally used instead of @experimental. However, that might be a rare mistake that would only happen until the term "stable getter" is more widely familiar and understood.

Also currently, I believe it would render on dart doc pages as @unstable without other information. I imagine that could definitely be mistaken as being an experimental marker.

eernstg · 2023-09-28T12:28:24Z

Perhaps we should make it @unstableGetter after all. That one should be quite informative for anyone who has encountered the concept at all. @lrhn's comment here would still apply, no matter which name is chosen.

eernstg · 2023-09-28T12:57:54Z

/// Annotation for a final instance variable indicating that the implicitly
/// induced getter of that variable is not intended to be stable.
///
/// This annotation is associated with the lint `avoid_unstable_final_fields`,
/// and it has no effect unless that lint is enabled.
///
/// When a final instance variable does not have this annotation, it is assumed
/// to induce a stable getter, and the lint will flag the overriding 
/// declarations that cause this getter to be unstable (that is, the overriding
/// getters which may return different results on different invocations with
/// the same receiver).
/// 
/// When a final instance variable has this annotation, it is not assumed to
/// induce a stable getter, and overriding getters are not flagged, whether or
/// not they are stable.
///
/// Intuitively, this combination of lint and annotation is intended to have the
/// following effect: By default, every final instance variable is an immutable
/// property of the receiver. If a property is declared as a final instance
/// variable, but it is not intended to be immutable then it should have this
/// annotation. The lint will flag locations where this assumption is violated.
///
/// In addition, tools such as the analyzer can provide feedback if the
/// annotation is applied to anything other than a final instance variable.

bwilkerson · 2023-09-28T15:06:20Z

Perhaps we should make it @unstableGetter after all.

I'm ok with that.

pq · 2023-09-28T18:56:16Z

Perhaps we should make it @unstableGetter after all.

I'm ok with that.

Me too.

eernstg · 2023-10-11T12:18:01Z

See https://dart-review.googlesource.com/c/sdk/+/330101.

pq self-assigned this Sep 27, 2023

pq changed the title ~~[proposal] add an @unstable annotation~~ [proposal] add an @unstableGetter annotation Sep 28, 2023

bwilkerson added area-devexp For issues related to the analysis server, IDE support, linter, `dart fix`, and diagnostic messages. and removed legacy-area-analyzer Use area-devexp instead. labels Feb 21, 2025

pq removed their assignment Apr 14, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[proposal] add an `@unstableGetter` annotation #53632

[proposal] add an `@unstableGetter` annotation #53632

[proposal] add an @unstableGetter annotation #53632

[proposal] add an @unstableGetter annotation #53632

Comments

[proposal] add an `@unstableGetter` annotation #53632

[proposal] add an `@unstableGetter` annotation #53632