Update doc comments, bump version to 1.0.0-wip (#268)

Author: kevmoo

CHANGELOG.md

@@ -1,4 +1,4 @@
-## 0.6.0-wip
+## 1.0.0-wip
 
 - Added supertypes' fields to dictionary constructors as dictionaries are
   allowed to contain those fields.

lib/src/dom/clipboard_apis.dart

@@ -83,6 +83,15 @@ extension type ClipboardItem._(JSObject _) implements JSObject {
     ClipboardItemOptions options,
   ]);
 
+  /// The **`supports()`** static method of the [ClipboardItem] interface
+  /// returns `true` if the given  is supported by the clipboard, and `false`
+  /// otherwise.
+  ///
+  /// Note that the
+  /// [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API)
+  /// mandates support for plain text, HTML and PNG files.
+  /// The `supports()` method will always return `true` for these MIME types, so
+  /// testing them is unnecessary .
   external static bool supports(String type);
 
   /// The **`getType()`** method of the [ClipboardItem] interface returns a

lib/src/dom/css_conditional.dart

@@ -29,7 +29,7 @@ import 'cssom.dart';
 /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/CSSConditionRule).
 extension type CSSConditionRule._(JSObject _)
     implements CSSGroupingRule, JSObject {
-  /// The **`conditionText`** property of
+  /// The read-only **`conditionText`** property of
   /// the [CSSConditionRule] interface returns or sets the text of the CSS
   /// rule.
   external String get conditionText;

lib/src/dom/css_view_transitions.dart

@@ -16,14 +16,22 @@ import 'dart:js_interop';
 typedef UpdateCallback = JSFunction;
 
 /// The **`ViewTransition`** interface of the [View Transitions API] represents
-/// a view transition, and provides functionality to react to the transition
-/// reaching different states (e.g. ready to run the animation, or animation
-/// finished) or skip the transition altogether.
+/// an active view transition, and provides functionality to react to the
+/// transition reaching different states (e.g. ready to run the animation, or
+/// animation finished) or skip the transition altogether.
 ///
-/// This object type is returned by the [Document.startViewTransition] method.
-/// When `startViewTransition()` is invoked, a sequence of steps is followed as
-/// explained in
-/// [The view transition process](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#the_view_transition_process).
+/// This object type is made available in the following ways:
+///
+/// - In the case of same-document (SPA) transitions, it is returned by the
+///   [Document.startViewTransition] method.
+/// - In the case of cross-document (MPA) transitions, it is made available:
+///   - In the outgoing page via the [Window.pageswap_event] event object's [PageSwapEvent.viewTransition] property.
+///   - In the inbound page via the [Window.pagereveal_event] event object's [PageRevealEvent.viewTransition] property.
+///
+/// When a view transition is triggered by a `startViewTransition()` call (or a
+/// page navigation in the case of MPA transitions), a sequence of steps is
+/// followed as explained in
+/// [The view transition process](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API/Using#the_view_transition_process).
 /// This also explains when the different promises fulfill.
 ///
 /// ---
@@ -33,18 +41,21 @@ typedef UpdateCallback = JSFunction;
 extension type ViewTransition._(JSObject _) implements JSObject {
   /// The **`skipTransition()`** method of the
   /// [ViewTransition] interface skips the animation part of the view
-  /// transition, but doesn't skip running the [Document.startViewTransition]
-  /// callback that updates the DOM.
+  /// transition, but doesn't skip running the associated view update.
   external void skipTransition();
 
   /// The **`updateCallbackDone`** read-only property of the
   /// [ViewTransition] interface is a `Promise` that fulfills when the promise
-  /// returned by the [Document.startViewTransition]'s callback fulfills, or
-  /// rejects when it rejects.
+  /// returned by the [Document.startViewTransition] method's callback fulfills,
+  /// or rejects when it rejects.
   ///
   /// `updateCallbackDone` is useful when you don't care about the
-  /// success/failure of the transition animation, and just want to know if and
-  /// when the DOM is updated.
+  /// success/failure of a same-document (SPA) view transition animation, and
+  /// just want to know if and when the DOM is updated.
+  ///
+  /// > **Note:** In the case of a cross-document (MPA) view transition, the
+  /// > `updateCallbackDone` promise of the associated `ViewTransition` is
+  /// > automatically fulfilled.
   external JSPromise<JSAny?> get updateCallbackDone;
 
   /// The **`ready`** read-only property of the
@@ -53,7 +64,7 @@ extension type ViewTransition._(JSObject _) implements JSObject {
   /// start.
   ///
   /// `ready` will reject if the transition cannot begin. This can be due to
-  /// misconfiguration, for example duplicate s, or if the callback passed to
+  /// misconfiguration, for example, duplicate s, or if the callback passed to
   /// [Document.startViewTransition] throws or returns a promise that rejects.
   external JSPromise<JSAny?> get ready;
 
@@ -62,12 +73,13 @@ extension type ViewTransition._(JSObject _) implements JSObject {
   /// transition animation is finished, and the new page view is visible and
   /// interactive to the user.
   ///
-  /// `finished` only rejects if the callback passed to
-  /// [Document.startViewTransition]throws or returns a promise that rejects,
-  /// which indicates that the new state of the page wasn't created.
+  /// `finished` will only reject in the case of a same-document (SPA)
+  /// transition, if the callback passed to [Document.startViewTransition]
+  /// throws or returns a promise that rejects. This would indicate that the new
+  /// state of the page wasn't created.
   ///
-  /// If a transition animation fails to start, or is skipped during the
-  /// animation using [ViewTransition.skipTransition], the end state is still
-  /// reached therefore `finished` still fulfills.
+  /// If a transition animation fails to start or is skipped during the
+  /// transition using [ViewTransition.skipTransition], the end state is still
+  /// reached therefore `finished` will still fulfill.
   external JSPromise<JSAny?> get finished;
 }

lib/src/dom/cssom.dart

@@ -296,16 +296,19 @@ extension type StyleSheetList._(JSObject _) implements JSObject {
 /// [CSSStyleSheet.insertRule] and [CSSStyleSheet.deleteRule], which are methods
 /// of [CSSStyleSheet].
 ///
-/// The interface has no constructor. An instance of `CSSRuleList` is returned
-/// by [CSSStyleSheet.cssRules] and [CSSKeyframesRule.cssRules].
+/// This interface was an
+/// [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156)
+/// and only continues to be supported to not break code that's already using
+/// it. Modern APIs represent list structures using types based on JavaScript
+/// [arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array),
+/// thus making many array methods available, and at the same time imposing
+/// additional semantics on their usage (such as making their items read-only).
 ///
-/// > **Note:** This interface was an
-/// > [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156)
-/// > and only continues to be supported to not break code that's already using
-/// > it. Modern APIs use types that wrap around ECMAScript array types instead,
-/// > so you can treat them like ECMAScript arrays, and at the same time impose
-/// > additional semantics on their usage (such as making their items
-/// > read-only).
+/// These historical reasons do not mean that you as a developer should avoid
+/// `CSSRuleList`. You don't create `CSSRuleList` objects yourself, but you get
+/// them from APIs such as [CSSStyleSheet.cssRules] and
+/// [CSSKeyframesRule.cssRules], and these APIs are not deprecated. However, be
+/// careful of the semantic differences from a real array.
 ///
 /// ---
 ///