Update MDN documentation (#213)

Author: kevmoo

lib/src/dom/cssom.dart

@@ -264,13 +264,12 @@ extension type CSSStyleSheetInit._(JSObject _) implements JSObject {
 /// However it can be iterated over in a standard `for` loop over its indices,
 /// or converted to an `Array`.
 ///
-/// > **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).
+/// > **Note:** Typically list interfaces like `StyleSheetList` wrap around
+/// > `Array` types, so you can use `Array` methods on them.
+/// > This is not the case here for
+/// > [historical reasons](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156).
+/// > However, you can convert `StyleSheetList` to an `Array` in order to use
+/// > those methods (see the example below).
 ///
 /// ---
 ///

lib/src/dom/html.dart

@@ -3050,7 +3050,7 @@ extension type HTMLVideoElement._(JSObject _)
   external VideoPlaybackQuality getVideoPlaybackQuality();
 
   /// The **`width`** property of the [HTMLVideoElement] interface returns an
-  /// integer that that reflects the `width` attribute of the `video` element,
+  /// integer that reflects the `width` attribute of the `video` element,
   /// specifying the displayed width of the resource in CSS pixels.
   external int get width;
   external set width(int value);
@@ -9113,27 +9113,25 @@ extension type Window._(JSObject _) implements EventTarget, JSObject {
   /// This method will block while the print dialog is open.
   external void print();
 
-  /// The **`window.postMessage()`** method safely enables
-  /// cross-origin communication between [Window] objects; _e.g.,_ between
-  /// a page and a pop-up that it spawned, or between a page and an iframe
-  /// embedded within it.
+  /// The **`window.postMessage()`** method safely enables cross-origin
+  /// communication between [Window] objects; _e.g.,_ between a page and a
+  /// pop-up that it spawned, or between a page and an iframe embedded within
+  /// it.
   ///
   /// Normally, scripts on different pages are allowed to access each other if
-  /// and only if
-  /// the pages they originate from share the same protocol, port number, and
-  /// host (also known
-  /// as the
+  /// and only if the pages they originate from share the same protocol, port
+  /// number, and host (also known as the
   /// "[same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)").
   /// `window.postMessage()` provides a controlled mechanism to securely
   /// circumvent this restriction (if used properly).
   ///
   /// Broadly, one window may obtain a reference to another (_e.g.,_ via
-  /// `targetWindow = window.opener`), and then dispatch a
-  /// [MessageEvent] on it with `targetWindow.postMessage()`. The
-  /// receiving window is then free to
+  /// `targetWindow = window.opener`), and then dispatch a [MessageEvent] on it
+  /// with `targetWindow.postMessage()`.
+  /// The receiving window is then free to
   /// [handle this event](https://developer.mozilla.org/en-US/docs/Web/Events/Event_handlers)
-  /// as needed. The arguments passed to `window.postMessage()`
-  /// (_i.e.,_ the "message") are
+  /// as needed.
+  /// The arguments passed to `window.postMessage()` (_i.e.,_ the "message") are
   /// [exposed to the receiving window through the event object](#the_dispatched_event).
   external void postMessage(
     JSAny? message, [

lib/src/dom/navigation_timing.dart

@@ -161,6 +161,19 @@ extension type PerformanceNavigationTiming._(JSObject _)
   /// Note that client side redirects, such as `<meta http-equiv="refresh"
   /// content="0; url=https://example.com/">` are not considered here.
   external int get redirectCount;
+
+  /// A website can indicate that a particular
+  /// [Client Hint](https://developer.mozilla.org/en-US/docs/Web/HTTP/Client_hints)
+  /// is critical to the page by including it in a  HTTP response header (as
+  /// well as the  HTTP request header which is needed for all client hints
+  /// whether critical or not). Doing so will trigger a connection restart if
+  /// the hint listed in the `Critical-CH` HTTP response header could have been,
+  /// but wasn't, included in the HTTP request initially sent. If the browser
+  /// does not support that client hint, it is ignored and no connection restart
+  /// occurs.
+  ///
+  /// The **`criticalCHRestart`** read-only property represents the time at
+  /// which the connection restart occurred.
   external DOMHighResTimeStamp get criticalCHRestart;
 }
 

lib/src/dom/webgl2.dart

@@ -1946,13 +1946,22 @@ extension type WebGL2RenderingContext._(JSObject _) implements JSObject {
   /// binds a
   /// passed [WebGLVertexArrayObject] object to the buffer.
   external void bindVertexArray(WebGLVertexArrayObject? array);
+
+  /// The **`WebGL2RenderingContext.bufferData()`** method of the
+  /// [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API)
+  /// creates and initializes the buffer object's data store.
   external void bufferData(
     GLenum target,
     JSAny sizeOrSrcData,
     GLenum usage, [
     int srcOffset,
     GLuint length,
   ]);
+
+  /// The **`WebGL2RenderingContext.bufferSubData()`** method of the
+  /// [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API)
+  /// updates a subset of a buffer
+  /// object's data store.
   external void bufferSubData(
     GLenum target,
     GLintptr dstByteOffset,

lib/src/dom/webrtc_stats.dart

@@ -91,6 +91,40 @@ extension type RTCRtpStreamStats._(JSObject _) implements RTCStats, JSObject {
   external String get codecId;
   external set codecId(String value);
 }
+
+/// The **`RTCCodecStats`** dictionary of the
+/// [WebRTC API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API)
+/// provides statistics about a codec used by  streams that are being sent or
+/// received by the associated [RTCPeerConnection] object.
+///
+/// These statistics can be obtained by iterating the [RTCStatsReport] object
+/// returned by [RTCPeerConnection.getStats] until you find an entry with the
+/// [`type`](#type) of `codec`.
+///
+/// The codec statistics can be correlated with the inbound or outbound stream
+/// statistics (both local and remote) by matching their `codecId` property to
+/// the codec's `id`.
+/// For example, if
+/// [`RTCInboundRtpStreamStats.codecId`](/en-US/docs/Web/API/RTCInboundRtpStreamStats#codecid)
+/// matches an [`RTCCodecStats.id`](#id) in the same report, then we know that
+/// the codec is being used on this peer connection's inbound stream.
+/// If no stream `codecId` references a codec statistic, then that codec
+/// statistic object is deleted — if the codec is used again, the statistics
+/// object will be recreated with the same `id`.
+///
+/// Codec objects may be referenced by multiple RTP streams in media sections
+/// using the same transport.
+/// In fact, user agents are expected to consolidate information into a single
+/// "codec" entry per payload type per transport (unless
+/// [sdpFmtpLine](#sdpfmtpline) is different when sending or receiving, in which
+/// case, different codecs will be needed for encoding and decoding).
+/// Note that other transports will use their own distinct `RTCCodecStats`
+/// objects.
+///
+/// ---
+///
+/// API documentation sourced from
+/// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/RTCCodecStats).
 extension type RTCCodecStats._(JSObject _) implements RTCStats, JSObject {
   external factory RTCCodecStats({
     required DOMHighResTimeStamp timestamp,
@@ -104,16 +138,51 @@ extension type RTCCodecStats._(JSObject _) implements RTCStats, JSObject {
     String sdpFmtpLine,
   });
 
+  /// The **`payloadType`** property of the [RTCCodecStats] dictionary is a
+  /// positive integer in the range from 0 to 127 that describes the format of
+  /// the  payload used in RTP encoding or decoding.
   external int get payloadType;
   external set payloadType(int value);
+
+  /// The **`transportId`** property of the [RTCCodecStats] dictionary is a
+  /// string that contains the unique identifier of the corresponding transport
+  /// on which this codec is being used.
+  ///
+  /// You can correlate the codec and associated transport statistics by
+  /// matching the `RTCCodecStats.transportId` with an [RTCTransportStats.id]
+  /// value.
   external String get transportId;
   external set transportId(String value);
+
+  /// The **`mimeType`** property of the [RTCCodecStats] dictionary is a string
+  /// containing the codec's  and subtype.
+  ///
+  /// This is of the form `"type/subtype"`, such as "video/VP8" or "audio/opus",
+  /// as defined in the
+  /// [IANA registry of valid MIME types](https://www.iana.org/assignments/rtp-parameters/rtp-parameters.xhtml#rtp-parameters-2).
   external String get mimeType;
   external set mimeType(String value);
+
+  /// The **`clockRate`** property of the [RTCCodecStats] dictionary is a
+  /// positive number containing the media sampling rate in hertz (Hz).
   external int get clockRate;
   external set clockRate(int value);
+
+  /// The **`channels`** property of the [RTCCodecStats] dictionary is a
+  /// positive number containing the number of channels supported by the codec.
+  ///
+  /// For audio codecs, a value of 1 specifies monaural sound while 2 indicates
+  /// stereo.
   external int get channels;
   external set channels(int value);
+
+  /// The **`sdpFmtpLine`** property of the [RTCCodecStats] dictionary is a
+  /// string containing the format-specific parameters of the codec.
+  ///
+  /// These are the values in the `"a=fmtp"` line in the codec's  (if present)
+  /// after the payload type number (see [section 5.8 of the IETF specification
+  /// for
+  /// JSEP](https://datatracker.ietf.org/doc/html/draft-ietf-rtcweb-jsep-24#section-5.8)).
   external String get sdpFmtpLine;
   external set sdpFmtpLine(String value);
 }