Address some Web Extension API feedback.

https://webkit.org/b/263908
rdar://problem/117697589

Reviewed by Brian Weinstein.

Added WK_NULLABLE_RESULT define to WKFoundation and use it in completionHandlers that can
have nil results without an error.

Also added WK_SWIFT_ASYNC_THROWS_ON_FALSE as an alias for NS_SWIFT_ASYNC_THROWS_ON_FALSE.

Adjusted some wording in the HeaderDoc comments too.

* Source/WebKit/Shared/API/Cocoa/WKFoundation.h:
* Source/WebKit/UIProcess/API/Cocoa/WKWebView.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtension.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionContext.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionControllerConfiguration.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionControllerDelegate.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionMessagePort.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionTab.h:
* Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionTabCreationOptions.h:

Canonical link: https://commits.webkit.org/270067@main

Source/WebKit/Shared/API/Cocoa/WKFoundation.h

@@ -44,6 +44,18 @@
 #define WK_SWIFT_ASYNC(...)
 #endif
 
+#ifdef NS_SWIFT_ASYNC_THROWS_ON_FALSE
+#define WK_SWIFT_ASYNC_THROWS_ON_FALSE(...) NS_SWIFT_ASYNC_THROWS_ON_FALSE(__VA_ARGS__)
+#else
+#define WK_SWIFT_ASYNC_THROWS_ON_FALSE(...)
+#endif
+
+#if __has_attribute(swift_async_error)
+#define WK_NULLABLE_RESULT _Nullable_result
+#else
+#define WK_NULLABLE_RESULT _Nullable
+#endif
+
 #ifndef WK_FRAMEWORK_HEADER_POSTPROCESSING_ENABLED
 
 #define WK_API_AVAILABLE(...)

Source/WebKit/UIProcess/API/Cocoa/WKWebView.h

@@ -344,11 +344,7 @@ typedef NS_ENUM(NSInteger, WKFullscreenState) {
 
  The above function text will create a promise that will fulfull with the value 42 after a one second delay, wait for it to resolve, then return the fulfillment value of 42.
 */
-#ifdef NS_SWIFT_ASYNC_NAME
-- (void)callAsyncJavaScript:(NSString *)functionBody arguments:(nullable NSDictionary<NSString *, id> *)arguments inFrame:(nullable WKFrameInfo *)frame inContentWorld:(WKContentWorld *)contentWorld completionHandler:(void (^ _Nullable)(_Nullable_result id, NSError * _Nullable error))completionHandler NS_REFINED_FOR_SWIFT WK_API_AVAILABLE(macos(11.0), ios(14.0));
-#else
-- (void)callAsyncJavaScript:(NSString *)functionBody arguments:(nullable NSDictionary<NSString *, id> *)arguments inFrame:(nullable WKFrameInfo *)frame inContentWorld:(WKContentWorld *)contentWorld completionHandler:(void (^ _Nullable)(_Nullable id, NSError * _Nullable error))completionHandler NS_REFINED_FOR_SWIFT WK_API_AVAILABLE(macos(11.0), ios(14.0));
-#endif
+- (void)callAsyncJavaScript:(NSString *)functionBody arguments:(nullable NSDictionary<NSString *, id> *)arguments inFrame:(nullable WKFrameInfo *)frame inContentWorld:(WKContentWorld *)contentWorld completionHandler:(void (^ _Nullable)(id WK_NULLABLE_RESULT result, NSError * _Nullable error))completionHandler NS_REFINED_FOR_SWIFT WK_API_AVAILABLE(macos(11.0), ios(14.0));
 
 /*! @abstract Closes all out-of-window media presentations in a WKWebView.
  @discussion Includes picture-in-picture and fullscreen.

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtension.h

@@ -151,8 +151,7 @@ WK_CLASS_AVAILABLE(macos(13.3), ios(16.4))
 @property (nonatomic, nullable, readonly, copy) NSString *displayDescription;
 
 /*!
- @abstract The default localized extension action label.
- @result The action label, or `nil` if there was no default action label specified.
+ @abstract The default localized extension action label. Returns `nil` if there was no default action label specified.
  @discussion This label serves as a default and should be used to represent the extension in contexts like action sheets or toolbars prior to
  the extension being loaded into an extension context. Once the extension is loaded, use the `actionForTab:` API to get the tab-specific label.
  */

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionContext.h

@@ -523,7 +523,7 @@ WK_CLASS_AVAILABLE(macos(13.3), ios(16.4))
 @property (nonatomic, readonly, copy) NSArray<id <_WKWebExtensionWindow>> *openWindows;
 
 /*!
- @abstract The window that currently has focus.
+ @abstract The window that currently has focus for this extension.
  @discussion This property holds the window object that currently has focus, as set by the `didFocusWindow:` method.
  It will be \c nil if no window has focus or if a window has focus that is not visible to the extension.  Initially populated by the window
  returned by the extension controller delegate method `webExtensionController:focusedWindowForExtensionContext:`.

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionControllerConfiguration.h

@@ -40,8 +40,8 @@ WK_CLASS_AVAILABLE(macos(13.3), ios(16.4))
 NS_SWIFT_NAME(_WKWebExtensionController.Configuration)
 @interface _WKWebExtensionControllerConfiguration : NSObject <NSSecureCoding, NSCopying>
 
-- (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;
+- (instancetype)init NS_UNAVAILABLE;
 
 /*!
  @abstract Returns a new default configuration that is persistent and not unique.

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionControllerDelegate.h

@@ -58,7 +58,7 @@ WK_API_AVAILABLE(macos(13.3), ios(16.4))
  indicates no open windows are available for the extension. Defaults to empty array if not implemented.
  @seealso webExtensionController:focusedWindowForExtensionContext:
  */
-- (NSArray<id <_WKWebExtensionWindow>> *)webExtensionController:(_WKWebExtensionController *)controller openWindowsForExtensionContext:(_WKWebExtensionContext *)extensionContext NS_SWIFT_NAME(webExtensionController(_:windowsFor:));
+- (NSArray<id <_WKWebExtensionWindow>> *)webExtensionController:(_WKWebExtensionController *)controller openWindowsForExtensionContext:(_WKWebExtensionContext *)extensionContext;
 
 /*!
  @abstract Called when an extension context requests the currently focused window.
@@ -69,35 +69,33 @@ WK_API_AVAILABLE(macos(13.3), ios(16.4))
  If not implemented, the first window in the result of `webExtensionController:openWindowsForExtensionContext:` is used.
  @seealso webExtensionController:openWindowsForExtensionContext:
  */
-- (nullable id <_WKWebExtensionWindow>)webExtensionController:(_WKWebExtensionController *)controller focusedWindowForExtensionContext:(_WKWebExtensionContext *)extensionContext NS_SWIFT_NAME(webExtensionController(_:focusedWindowFor:));
+- (nullable id <_WKWebExtensionWindow>)webExtensionController:(_WKWebExtensionController *)controller focusedWindowForExtensionContext:(_WKWebExtensionContext *)extensionContext;
 
 /*!
  @abstract Called when an extension context requests a new window to be opened.
  @param controller The web extension controller that is managing the extension.
  @param options The set of options specifying how the new window should be created.
  @param extensionContext The context in which the web extension is running.
  @param completionHandler A block to be called with the newly created window or \c nil if the window wasn't created. An error should be
- provided if any errors occured.
+ provided if any errors occurred.
  @discussion This method should be implemented by the app to handle requests to open new windows. The app can decide how to handle
  the creation based on the provided options and existing windows. Once handled, the app should call the completion block with the created window
- or `nil` if the creation was declined or failed. If not implemented or the completion block is not called within a reasonable amount of time, the
- request is assumed to have been denied.
+ or `nil` if the creation was declined or failed. If not implemented, the extension can't open new windows.
  */
-- (void)webExtensionController:(_WKWebExtensionController *)controller openNewWindowWithOptions:(_WKWebExtensionWindowCreationOptions *)options forExtensionContext:(_WKWebExtensionContext *)extensionContext completionHandler:(void (^)(id <_WKWebExtensionWindow> _Nullable newWindow, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(webExtensionController(_:openNewWindowWithOptions:for:completionHandler:));
+- (void)webExtensionController:(_WKWebExtensionController *)controller openNewWindowWithOptions:(_WKWebExtensionWindowCreationOptions *)options forExtensionContext:(_WKWebExtensionContext *)extensionContext completionHandler:(void (^)(id <_WKWebExtensionWindow> WK_NULLABLE_RESULT newWindow, NSError * _Nullable error))completionHandler;
 
 /*!
  @abstract Called when an extension context requests a new tab to be opened.
  @param controller The web extension controller that is managing the extension.
  @param options The set of options specifying how the new tab should be created.
  @param extensionContext The context in which the web extension is running.
  @param completionHandler A block to be called with the newly created tab or \c nil if the tab wasn't created. An error should be
- provided if any errors occured.
+ provided if any errors occurred.
  @discussion This method should be implemented by the app to handle requests to open new tabs. The app can decide how to handle
  the creation based on the provided options and existing tabs. Once handled, the app should call the completion block with the created tab
- or `nil` if the creation was declined or failed. If not implemented or the completion block is not called within a reasonable amount of time,
- the request is assumed to have been denied.
+ or `nil` if the creation was declined or failed. If not implemented, the extension can't open new tabs.
  */
-- (void)webExtensionController:(_WKWebExtensionController *)controller openNewTabWithOptions:(_WKWebExtensionTabCreationOptions *)options forExtensionContext:(_WKWebExtensionContext *)extensionContext completionHandler:(void (^)(id <_WKWebExtensionTab> _Nullable newTab, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(webExtensionController(_:openNewTabWithOptions:for:completionHandler:));
+- (void)webExtensionController:(_WKWebExtensionController *)controller openNewTabWithOptions:(_WKWebExtensionTabCreationOptions *)options forExtensionContext:(_WKWebExtensionContext *)extensionContext completionHandler:(void (^)(id <_WKWebExtensionTab> WK_NULLABLE_RESULT newTab, NSError * _Nullable error))completionHandler;
 
 /*!
  @abstract Called when an extension context requests permissions.
@@ -162,7 +160,7 @@ WK_API_AVAILABLE(macos(13.3), ios(16.4))
  If not implemented, the default behavior is to pass the message to the app extension handler within the extension's bundle,
  if the extension was loaded from an app extension bundle; otherwise, no action is performed if not implemented.
  */
-- (void)webExtensionController:(_WKWebExtensionController *)controller sendMessage:(id)message toApplicationIdentifier:(nullable NSString *)applicationIdentifier forExtensionContext:(_WKWebExtensionContext *)extensionContext replyHandler:(void (^)(id _Nullable replyMessage, NSError * _Nullable error))replyHandler WK_SWIFT_ASYNC(5) NS_SWIFT_NAME(webExtensionController(_:sendMessage:to:for:replyHandler:));
+- (void)webExtensionController:(_WKWebExtensionController *)controller sendMessage:(id)message toApplicationIdentifier:(nullable NSString *)applicationIdentifier forExtensionContext:(_WKWebExtensionContext *)extensionContext replyHandler:(void (^)(id WK_NULLABLE_RESULT replyMessage, NSError * _Nullable error))replyHandler WK_SWIFT_ASYNC(5) NS_SWIFT_NAME(webExtensionController(_:sendMessage:to:for:replyHandler:));
 
 /*!
  @abstract Called when an extension context wants to establish a persistent connection to an application.

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionMessagePort.h

@@ -80,7 +80,7 @@ NS_SWIFT_NAME(_WKWebExtension.MessagePort)
  @param message The message that needs to be sent, which must be JSON-serializable.
  @param completionHandler An optional block to be invoked after the message is sent, taking a boolean and an optional error object as parameters.
  */
-- (void)sendMessage:(id)message completionHandler:(void (^ _Nullable)(BOOL success, NSError * _Nullable error))completionHandler;
+- (void)sendMessage:(id)message completionHandler:(void (^ _Nullable)(BOOL success, NSError * _Nullable error))completionHandler WK_SWIFT_ASYNC_THROWS_ON_FALSE(1);
 
 /*!
  @abstract Disconnects the port, terminating all further messages.

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionTab.h

@@ -68,6 +68,7 @@ typedef NS_OPTIONS(NSUInteger, _WKWebExtensionTabChangedProperties) {
     _WKWebExtensionTabChangedPropertiesAll        = NSUIntegerMax,
 } WK_API_AVAILABLE(macos(13.3), ios(16.4));
 
+/*! @abstract A class conforming to the `WKWebExtensionTab` protocol represents a tab to web extensions. */
 WK_API_AVAILABLE(macos(13.3), ios(16.4))
 @protocol _WKWebExtensionTab <NSObject>
 @optional
@@ -285,7 +286,7 @@ WK_API_AVAILABLE(macos(13.3), ios(16.4))
  the detected locale (or \c nil if the locale is unknown) and an error, which should be provided if any errors occurred.
  @discussion No action is performed if not implemented.
  */
-- (void)detectWebpageLocaleForWebExtensionContext:(_WKWebExtensionContext *)context completionHandler:(void (^)(NSLocale * _Nullable locale, NSError * _Nullable error))completionHandler;
+- (void)detectWebpageLocaleForWebExtensionContext:(_WKWebExtensionContext *)context completionHandler:(void (^)(NSLocale * WK_NULLABLE_RESULT locale, NSError * _Nullable error))completionHandler;
 
 /*!
  @abstract Called to capture the visible area of the current webpage as an image.
@@ -295,9 +296,9 @@ WK_API_AVAILABLE(macos(13.3), ios(16.4))
  @discussion Defaults to capturing the visible area for the main web view if not implemented.
  */
 #if TARGET_OS_IPHONE
-- (void)captureVisibleWebpageForWebExtensionContext:(_WKWebExtensionContext *)context completionHandler:(void (^)(UIImage * _Nullable visibleWebpageImage, NSError * _Nullable error))completionHandler;
+- (void)captureVisibleWebpageForWebExtensionContext:(_WKWebExtensionContext *)context completionHandler:(void (^)(UIImage * WK_NULLABLE_RESULT visibleWebpageImage, NSError * _Nullable error))completionHandler;
 #else
-- (void)captureVisibleWebpageForWebExtensionContext:(_WKWebExtensionContext *)context completionHandler:(void (^)(NSImage * _Nullable visibleWebpageImage, NSError * _Nullable error))completionHandler;
+- (void)captureVisibleWebpageForWebExtensionContext:(_WKWebExtensionContext *)context completionHandler:(void (^)(NSImage * WK_NULLABLE_RESULT visibleWebpageImage, NSError * _Nullable error))completionHandler;
 #endif
 
 /*!
@@ -400,7 +401,7 @@ WK_API_AVAILABLE(macos(13.3), ios(16.4))
  @discussion This is equivalent to the user selecting to duplicate the tab through a menu item, with the specified options.
  No action is performed if not implemented.
  */
-- (void)duplicateForWebExtensionContext:(_WKWebExtensionContext *)context withOptions:(_WKWebExtensionTabCreationOptions *)options completionHandler:(void (^)(id <_WKWebExtensionTab> _Nullable duplicatedTab, NSError * _Nullable error))completionHandler;
+- (void)duplicateForWebExtensionContext:(_WKWebExtensionContext *)context withOptions:(_WKWebExtensionTabCreationOptions *)options completionHandler:(void (^)(id <_WKWebExtensionTab> WK_NULLABLE_RESULT duplicatedTab, NSError * _Nullable error))completionHandler;
 
 /*!
  @abstract Called to close the tab.

Source/WebKit/UIProcess/API/Cocoa/_WKWebExtensionTabCreationOptions.h

@@ -33,9 +33,9 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /*!
- @abstract A `_WKWebExtensionWindowCreationOptions` object encapsulates new window creation options for an extension.
- @discussion This class holds the various options that influence the behavior and initial state of a newly created window.
- The app retains the discretion to disregard any or all of these options, or even opt not to create a new window.
+ @abstract A `_WKWebExtensionTabCreationOptions` object encapsulates new tab creation options for an extension.
+ @discussion This class holds the various options that influence the behavior and initial state of a newly created tab.
+ The app retains the discretion to disregard any or all of these options, or even opt not to create a new tab.
  */
 WK_CLASS_AVAILABLE(macos(WK_MAC_TBA), ios(WK_IOS_TBA))
 @interface _WKWebExtensionTabCreationOptions : NSObject