Generate api docs for getters (#207)

* commit dom.dart

* generate docs for getters

* re-generate the dom libraries

* update the changelog

Author: devoncarew

CHANGELOG.md

@@ -4,6 +4,7 @@
   allowed to contain those fields.
 - Empty dictionary constructors now create an empty object instead of being
   treated like non-object literal `external` constructors.
+- Generate MDN API documentation for getters.
 - Update the docs for generated interface types to reference the MDN Web Docs
   project.
 - Address several broken links in API documentation.

analysis_options.yaml

@@ -35,7 +35,6 @@ linter:
   - no_runtimeType_toString
   - package_api_docs
   - prefer_const_declarations
-  - prefer_expression_function_bodies
   - prefer_final_locals
   - unnecessary_await_in_return
   - use_string_buffers

lib/src/dom/clipboard_apis.dart

@@ -29,8 +29,8 @@ extension type ClipboardEventInit._(JSObject _) implements EventInit, JSObject {
     DataTransfer? clipboardData,
   });
 
-  external set clipboardData(DataTransfer? value);
   external DataTransfer? get clipboardData;
+  external set clipboardData(DataTransfer? value);
 }
 
 /// The **`ClipboardEvent`** interface of the
@@ -49,6 +49,17 @@ extension type ClipboardEvent._(JSObject _) implements Event, JSObject {
     ClipboardEventInit eventInitDict,
   ]);
 
+  /// The **`clipboardData`** property of the [ClipboardEvent] interface holds a
+  /// [DataTransfer] object, which can be used to:
+  ///
+  /// - specify what data should be put into the clipboard from the
+  ///   [Element.cut_event] and [Element.copy_event] event handlers, typically
+  ///   with a [DataTransfer.setData] call;
+  /// - obtain the data to be pasted from the [Element.paste_event] event
+  ///   handler, typically with a [DataTransfer.getData] call.
+  ///
+  /// See the [Element.cut_event], [Element.copy_event], and
+  /// [Element.paste_event] events documentation for more information.
   external DataTransfer? get clipboardData;
 }
 
@@ -80,14 +91,23 @@ extension type ClipboardItem._(JSObject _) implements JSObject {
   /// `Promise` that resolves with a [Blob] of the requested  or an error if the
   /// MIME type is not found.
   external JSPromise<Blob> getType(String type);
+
+  /// The read-only **`presentationStyle`** property of the [ClipboardItem]
+  /// interface returns a string indicating how an item should be presented.
+  ///
+  /// For example, in some contexts an image might be displayed inline, while in
+  /// others it might be represented as an attachment.
   external PresentationStyle get presentationStyle;
+
+  /// The read-only **`types`** property of the [ClipboardItem] interface
+  /// returns an `Array` of  available within the [ClipboardItem]
   external JSArray<JSString> get types;
 }
 extension type ClipboardItemOptions._(JSObject _) implements JSObject {
   external factory ClipboardItemOptions({PresentationStyle presentationStyle});
 
-  external set presentationStyle(PresentationStyle value);
   external PresentationStyle get presentationStyle;
+  external set presentationStyle(PresentationStyle value);
 }
 
 /// The **`Clipboard`** interface of the
@@ -151,8 +171,8 @@ extension type Clipboard._(JSObject _) implements EventTarget, JSObject {
 extension type ClipboardUnsanitizedFormats._(JSObject _) implements JSObject {
   external factory ClipboardUnsanitizedFormats({JSArray<JSString> unsanitized});
 
-  external set unsanitized(JSArray<JSString> value);
   external JSArray<JSString> get unsanitized;
+  external set unsanitized(JSArray<JSString> value);
 }
 extension type ClipboardPermissionDescriptor._(JSObject _)
     implements PermissionDescriptor, JSObject {
@@ -161,6 +181,6 @@ extension type ClipboardPermissionDescriptor._(JSObject _)
     bool allowWithoutGesture,
   });
 
-  external set allowWithoutGesture(bool value);
   external bool get allowWithoutGesture;
+  external set allowWithoutGesture(bool value);
 }

lib/src/dom/compression.dart

@@ -27,7 +27,12 @@ typedef CompressionFormat = String;
 extension type CompressionStream._(JSObject _) implements JSObject {
   external factory CompressionStream(CompressionFormat format);
 
+  /// The **`readable`** read-only property of the [CompressionStream] interface
+  /// returns a [ReadableStream].
   external ReadableStream get readable;
+
+  /// The **`writable`** read-only property of the [CompressionStream] interface
+  /// returns a [WritableStream].
   external WritableStream get writable;
 }
 
@@ -41,6 +46,11 @@ extension type CompressionStream._(JSObject _) implements JSObject {
 extension type DecompressionStream._(JSObject _) implements JSObject {
   external factory DecompressionStream(CompressionFormat format);
 
+  /// The **`readable`** read-only property of the [DecompressionStream]
+  /// interface returns a [ReadableStream].
   external ReadableStream get readable;
+
+  /// The **`writable`** read-only property of the [DecompressionStream]
+  /// interface returns a [WritableStream].
   external WritableStream get writable;
 }

lib/src/dom/credential_management.dart

@@ -38,7 +38,16 @@ typedef CredentialMediationRequirement = String;
 /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Credential).
 extension type Credential._(JSObject _) implements JSObject {
   external static JSPromise<JSBoolean> isConditionalMediationAvailable();
+
+  /// The **`id`** read-only property of the [Credential] interface returns a
+  /// string containing the credential's identifier. This might be a GUID,
+  /// username, or email address, or some other value, depending on the type of
+  /// credential.
   external String get id;
+
+  /// The **`type`** read-only property of the [Credential] interface returns a
+  /// string containing the credential's type. Valid values are `password`,
+  /// `federated`, `public-key`, `identity` and `otp`.
   external String get type;
 }
 
@@ -138,8 +147,8 @@ extension type CredentialsContainer._(JSObject _) implements JSObject {
 extension type CredentialData._(JSObject _) implements JSObject {
   external factory CredentialData({required String id});
 
-  external set id(String value);
   external String get id;
+  external set id(String value);
 }
 extension type CredentialRequestOptions._(JSObject _) implements JSObject {
   external factory CredentialRequestOptions({
@@ -150,16 +159,16 @@ extension type CredentialRequestOptions._(JSObject _) implements JSObject {
     PublicKeyCredentialRequestOptions publicKey,
   });
 
-  external set mediation(CredentialMediationRequirement value);
   external CredentialMediationRequirement get mediation;
-  external set signal(AbortSignal value);
+  external set mediation(CredentialMediationRequirement value);
   external AbortSignal get signal;
-  external set password(bool value);
+  external set signal(AbortSignal value);
   external bool get password;
-  external set federated(FederatedCredentialRequestOptions value);
+  external set password(bool value);
   external FederatedCredentialRequestOptions get federated;
-  external set publicKey(PublicKeyCredentialRequestOptions value);
+  external set federated(FederatedCredentialRequestOptions value);
   external PublicKeyCredentialRequestOptions get publicKey;
+  external set publicKey(PublicKeyCredentialRequestOptions value);
 }
 extension type CredentialCreationOptions._(JSObject _) implements JSObject {
   external factory CredentialCreationOptions({
@@ -169,14 +178,14 @@ extension type CredentialCreationOptions._(JSObject _) implements JSObject {
     PublicKeyCredentialCreationOptions publicKey,
   });
 
-  external set signal(AbortSignal value);
   external AbortSignal get signal;
-  external set password(PasswordCredentialInit value);
+  external set signal(AbortSignal value);
   external PasswordCredentialInit get password;
-  external set federated(FederatedCredentialInit value);
+  external set password(PasswordCredentialInit value);
   external FederatedCredentialInit get federated;
-  external set publicKey(PublicKeyCredentialCreationOptions value);
+  external set federated(FederatedCredentialInit value);
   external PublicKeyCredentialCreationOptions get publicKey;
+  external set publicKey(PublicKeyCredentialCreationOptions value);
 }
 
 /// The **`PasswordCredential`** interface of the
@@ -196,8 +205,23 @@ extension type PasswordCredential._(JSObject _)
     implements Credential, JSObject {
   external factory PasswordCredential(JSObject dataOrForm);
 
+  /// The **`password`** read-only property
+  /// of the [PasswordCredential] interface returns a string
+  /// containing the password of the credential.
   external String get password;
+
+  /// The **`name`** read-only property of
+  /// the [PasswordCredential] interface returns a string
+  /// containing a human-readable public name for display in a credential
+  /// chooser.
   external String get name;
+
+  /// The **`iconURL`** read-only property
+  /// of the [PasswordCredential] interface returns a string
+  /// containing a URL pointing to an image for an icon. This image is intended
+  /// for display
+  /// in a credential chooser. The URL must be accessible without
+  /// authentication.
   external String get iconURL;
 }
 extension type PasswordCredentialData._(JSObject _)
@@ -210,14 +234,14 @@ extension type PasswordCredentialData._(JSObject _)
     required String password,
   });
 
-  external set name(String value);
   external String get name;
-  external set iconURL(String value);
+  external set name(String value);
   external String get iconURL;
-  external set origin(String value);
+  external set iconURL(String value);
   external String get origin;
-  external set password(String value);
+  external set origin(String value);
   external String get password;
+  external set password(String value);
 }
 
 /// The **`FederatedCredential`** interface of the
@@ -244,7 +268,18 @@ extension type FederatedCredential._(JSObject _)
     implements Credential, JSObject {
   external factory FederatedCredential(FederatedCredentialInit data);
 
+  /// The **`provider`** property of the
+  /// [FederatedCredential] interface returns a string
+  /// containing a credential's federated identity provider.
   external String get provider;
+
+  /// The **`protocol`** property of the
+  /// [FederatedCredential] interface returns a read-only
+  /// string containing a credential's federated identity protocol. If this
+  /// property is
+  /// [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null),
+  /// the protocol may be inferred from the
+  /// [FederatedCredential.provider] property.
   external String? get protocol;
   external String get name;
   external String get iconURL;
@@ -256,10 +291,10 @@ extension type FederatedCredentialRequestOptions._(JSObject _)
     JSArray<JSString> protocols,
   });
 
-  external set providers(JSArray<JSString> value);
   external JSArray<JSString> get providers;
-  external set protocols(JSArray<JSString> value);
+  external set providers(JSArray<JSString> value);
   external JSArray<JSString> get protocols;
+  external set protocols(JSArray<JSString> value);
 }
 extension type FederatedCredentialInit._(JSObject _)
     implements CredentialData, JSObject {
@@ -272,14 +307,14 @@ extension type FederatedCredentialInit._(JSObject _)
     String protocol,
   });
 
-  external set name(String value);
   external String get name;
-  external set iconURL(String value);
+  external set name(String value);
   external String get iconURL;
-  external set origin(String value);
+  external set iconURL(String value);
   external String get origin;
-  external set provider(String value);
+  external set origin(String value);
   external String get provider;
-  external set protocol(String value);
+  external set provider(String value);
   external String get protocol;
+  external set protocol(String value);
 }

lib/src/dom/csp.dart

@@ -66,17 +66,70 @@ extension type SecurityPolicyViolationEvent._(JSObject _)
     SecurityPolicyViolationEventInit eventInitDict,
   ]);
 
+  /// The **`documentURI`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is a string
+  /// representing the URI of the document or worker in which the violation was
+  /// found.
   external String get documentURI;
+
+  /// The **`referrer`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is a string
+  /// representing the referrer of the resources whose policy was violated. This
+  /// will be a URL
+  /// or `null`.
   external String get referrer;
+
+  /// The **`blockedURI`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is a string
+  /// representing the URI of the resource that was blocked because it violates
+  /// a policy.
   external String get blockedURI;
+
+  /// The **`effectiveDirective`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is a string
+  /// representing the directive whose enforcement uncovered the violation.
   external String get effectiveDirective;
+
+  /// The **`violatedDirective`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is a string
+  /// representing the directive whose enforcement uncovered the violation.
   external String get violatedDirective;
+
+  /// The **`originalPolicy`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is a string
+  /// containing the policy whose enforcement uncovered the violation.
   external String get originalPolicy;
+
+  /// The **`sourceFile`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is a string
+  /// representing the URI of the document or worker in which the violation was
+  /// found.
   external String get sourceFile;
+
+  /// The **`sample`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is a string
+  /// representing a sample of the resource that caused the violation.
   external String get sample;
+
+  /// The **`disposition`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface indicates how the violated policy
+  /// is configured to be treated by the user agent.
   external SecurityPolicyViolationEventDisposition get disposition;
+
+  /// The **`statusCode`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is a number representing the HTTP
+  /// status code of the document or worker in which the violation occurred.
   external int get statusCode;
+
+  /// The **`lineNumber`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is the line number in the
+  /// document
+  /// or worker at which the violation occurred.
   external int get lineNumber;
+
+  /// The **`columnNumber`** read-only property of the
+  /// [SecurityPolicyViolationEvent] interface is the column number in the
+  /// document or worker at which the violation occurred.
   external int get columnNumber;
 }
 extension type SecurityPolicyViolationEventInit._(JSObject _)
@@ -99,28 +152,28 @@ extension type SecurityPolicyViolationEventInit._(JSObject _)
     int columnNumber,
   });
 
-  external set documentURI(String value);
   external String get documentURI;
-  external set referrer(String value);
+  external set documentURI(String value);
   external String get referrer;
-  external set blockedURI(String value);
+  external set referrer(String value);
   external String get blockedURI;
-  external set violatedDirective(String value);
+  external set blockedURI(String value);
   external String get violatedDirective;
-  external set effectiveDirective(String value);
+  external set violatedDirective(String value);
   external String get effectiveDirective;
-  external set originalPolicy(String value);
+  external set effectiveDirective(String value);
   external String get originalPolicy;
-  external set sourceFile(String value);
+  external set originalPolicy(String value);
   external String get sourceFile;
-  external set sample(String value);
+  external set sourceFile(String value);
   external String get sample;
-  external set disposition(SecurityPolicyViolationEventDisposition value);
+  external set sample(String value);
   external SecurityPolicyViolationEventDisposition get disposition;
-  external set statusCode(int value);
+  external set disposition(SecurityPolicyViolationEventDisposition value);
   external int get statusCode;
-  external set lineNumber(int value);
+  external set statusCode(int value);
   external int get lineNumber;
-  external set columnNumber(int value);
+  external set lineNumber(int value);
   external int get columnNumber;
+  external set columnNumber(int value);
 }