[dart:js_interop] Improve globalContext documentation

Fixes https://github.com/dart-lang/sdk/issues/60900

"globalContext.name" is confusing because it implies that's
the code it's executing rather than getting the property
'name' off of the globalContext getter.

Also adds a library annotation with no @JS annotation in the
example to make it clear there's no library renaming (because
otherwise we'd be fetching the rename first off of globalContext).

CoreLibraryReviewExempt: Doc-only change.
Change-Id: I77cac4b9fd7c29f06c1c579879126031ad6b8dac
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/434523
Reviewed-by: Erik Ernst <eernst@google.com>
Commit-Queue: Srujan Gaddam <srujzs@google.com>
This commit is contained in:
Srujan Gaddam
2025-06-13 12:26:12 -07:00
committed by Commit Queue
parent 265a970813
commit 2ed7779ff4
+4 -1
View File
@@ -1388,11 +1388,14 @@ extension JSAnyOperatorExtension on JSAny? {
/// For example:
///
/// ```
/// library;
///
/// @JS()
/// external String get name;
/// ```
///
/// Reading `name` will execute JavaScript code like `globalContext.name`.
/// Reading the top-level member `name` will execute JavaScript code like
/// `<globalContext>.name`.
///
/// There are subtle differences depending on the compiler, but in general,
/// [globalContext] can be treated like JavaScript's `globalThis`.