Some more copy-editing of the Modern WebKit headerdoc
authorggaren@apple.com <ggaren@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Fri, 30 May 2014 19:11:46 +0000 (19:11 +0000)
committerggaren@apple.com <ggaren@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Fri, 30 May 2014 19:11:46 +0000 (19:11 +0000)
https://bugs.webkit.org/show_bug.cgi?id=133408

Reviewed by Beth Dakin.

A copy-editor suggested some edits to the headerdoc for clarity,
style, and formatting.

I reviewed the edits and accepted about 80% of them.

* UIProcess/API/Cocoa/WKBackForwardList.h:
* UIProcess/API/Cocoa/WKBackForwardListItem.h:
* UIProcess/API/Cocoa/WKFrameInfo.h:
* UIProcess/API/Cocoa/WKNavigation.h:
* UIProcess/API/Cocoa/WKNavigationAction.h:
(NS_ENUM):
* UIProcess/API/Cocoa/WKNavigationDelegate.h:
(NS_ENUM):
* UIProcess/API/Cocoa/WKNavigationResponse.h:
* UIProcess/API/Cocoa/WKPreferences.h:
* UIProcess/API/Cocoa/WKProcessPool.h:
* UIProcess/API/Cocoa/WKScriptMessage.h:
* UIProcess/API/Cocoa/WKScriptMessageHandler.h:
* UIProcess/API/Cocoa/WKUIDelegate.h:
* UIProcess/API/Cocoa/WKUserContentController.h:
* UIProcess/API/Cocoa/WKWebView.h:
* UIProcess/API/Cocoa/WKWebViewConfiguration.h:

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@169490 268f45cc-cd09-0410-ab3c-d52691b4dbfc

16 files changed:
Source/WebKit2/ChangeLog
Source/WebKit2/UIProcess/API/Cocoa/WKBackForwardList.h
Source/WebKit2/UIProcess/API/Cocoa/WKBackForwardListItem.h
Source/WebKit2/UIProcess/API/Cocoa/WKFrameInfo.h
Source/WebKit2/UIProcess/API/Cocoa/WKNavigation.h
Source/WebKit2/UIProcess/API/Cocoa/WKNavigationAction.h
Source/WebKit2/UIProcess/API/Cocoa/WKNavigationDelegate.h
Source/WebKit2/UIProcess/API/Cocoa/WKNavigationResponse.h
Source/WebKit2/UIProcess/API/Cocoa/WKPreferences.h
Source/WebKit2/UIProcess/API/Cocoa/WKProcessPool.h
Source/WebKit2/UIProcess/API/Cocoa/WKScriptMessage.h
Source/WebKit2/UIProcess/API/Cocoa/WKScriptMessageHandler.h
Source/WebKit2/UIProcess/API/Cocoa/WKUIDelegate.h
Source/WebKit2/UIProcess/API/Cocoa/WKUserContentController.h
Source/WebKit2/UIProcess/API/Cocoa/WKWebView.h
Source/WebKit2/UIProcess/API/Cocoa/WKWebViewConfiguration.h

index 672912b..d9175d3 100644 (file)
@@ -1,3 +1,33 @@
+2014-05-30  Geoffrey Garen  <ggaren@apple.com>
+
+        Some more copy-editing of the Modern WebKit headerdoc
+        https://bugs.webkit.org/show_bug.cgi?id=133408
+
+        Reviewed by Beth Dakin.
+
+        A copy-editor suggested some edits to the headerdoc for clarity,
+        style, and formatting.
+
+        I reviewed the edits and accepted about 80% of them.
+
+        * UIProcess/API/Cocoa/WKBackForwardList.h:
+        * UIProcess/API/Cocoa/WKBackForwardListItem.h:
+        * UIProcess/API/Cocoa/WKFrameInfo.h:
+        * UIProcess/API/Cocoa/WKNavigation.h:
+        * UIProcess/API/Cocoa/WKNavigationAction.h:
+        (NS_ENUM):
+        * UIProcess/API/Cocoa/WKNavigationDelegate.h:
+        (NS_ENUM):
+        * UIProcess/API/Cocoa/WKNavigationResponse.h:
+        * UIProcess/API/Cocoa/WKPreferences.h:
+        * UIProcess/API/Cocoa/WKProcessPool.h:
+        * UIProcess/API/Cocoa/WKScriptMessage.h:
+        * UIProcess/API/Cocoa/WKScriptMessageHandler.h:
+        * UIProcess/API/Cocoa/WKUIDelegate.h:
+        * UIProcess/API/Cocoa/WKUserContentController.h:
+        * UIProcess/API/Cocoa/WKWebView.h:
+        * UIProcess/API/Cocoa/WKWebViewConfiguration.h:
+
 2014-05-30  Timothy Horton  <timothy_horton@apple.com>
 
         Crash loading skydrive.com (assertion under RemoteLayerTreeDisplayRefreshMonitor)
index efaac55..3efa8a6 100644 (file)
@@ -29,8 +29,8 @@
 
 #import <WebKit/WKBackForwardListItem.h>
 
-/*! @abstract A @link WKWebView @/link's list of previously-visited webpages that can be reached by
- going back or forward.
+/*! @abstract A WKBackForwardList object is a list of webpages previously
visited in a web view that can be reached by going back or forward.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKBackForwardList : NSObject
@@ -39,27 +39,35 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 @property (nonatomic, readonly) WKBackForwardListItem *currentItem;
 
-/*! @abstract The item right before the current item, or nil if there isn't one.
+/*! @abstract The item immediately preceding the current item, or nil
+if there isn't one.
  */
 @property (nonatomic, readonly) WKBackForwardListItem *backItem;
 
-/*! @abstract The item right after the current item, or nil if there isn't one.
+/*! @abstract The item immediately following the current item, or nil
+if there isn't one.
  */
 @property (nonatomic, readonly) WKBackForwardListItem *forwardItem;
 
-/*! @abstract Returns an item the given distance from the current item.
- @param index Index of the desired list item relative to the current item; 0 is current item, -1 is back item, 1 is forward item, etc.
- @result The item the given distance from the current item. If index exceeds the limits of the list, nil is returned.
+/*! @abstract Returns the item at a specified distance from the current
+ item.
+ @param index Index of the desired list item relative to the current item:
+ 0 for the current item, -1 for the immediately preceding item, 1 for the
+ immediately following item, and so on.
+ @result The item at the specified distance from the current item, or nil
+ if the index parameter exceeds the limits of the list.
  */
 - (WKBackForwardListItem *)itemAtIndex:(NSInteger)index;
 
-/*! @abstract Returns the portion of the list before the current item.
- @discussion The entries are in the order that they were originally visited.
+/*! @abstract The portion of the list preceding the current item.
+ @discussion The items are in the order in which they were originally
+ visited.
  */
 @property (nonatomic, readonly) NSArray *backList;
 
-/*! @abstract Returns the portion of the list after the current item.
- @discussion The entries are in the order that they were originally visited.
+/*! @abstract The portion of the list following the current item.
+ @discussion The items are in the order in which they were originally
+ visited.
  */
 @property (nonatomic, readonly) NSArray *forwardList;
 
index b5e2985..74c0a30 100644 (file)
@@ -29,7 +29,7 @@
 
 #import <Foundation/Foundation.h>
 
-/*! A @link WKBackForwardListItem @/link represents a visited webpage in a WKWebView's back-forward list.
+/*! A WKBackForwardListItem object represents a previously visited webpage in the back-forward list of a web view.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKBackForwardListItem : NSObject
index c311b60..b778607 100644 (file)
 
 #import <Foundation/Foundation.h>
 
-/*! A @link WKFrameInfo @/link object contains information about a frame on a webpage.
- @discussion WKFrameInfo objects are transient, data-only objects. A WKFrameInfo object
- does not uniquely identify a frame across multiple delegate method calls.
+/*! A WKFrameInfo object contains information about a frame on a webpage.
+ @discussion An instance of this class is a transient, data-only object;
+ it does not uniquely identify a frame across multiple delegate method
+ calls.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKFrameInfo : NSObject
 
-/*! @abstract Whether the frame is the main frame or a subframe.
+/*! @abstract A Boolean value indicating whether the frame is the main frame
+ or a subframe.
  */
 @property (nonatomic, readonly, getter=isMainFrame) BOOL mainFrame;
 
-/*! @abstract The current NSURLRequest of this frame.
+/*! @abstract The frame's current request.
  */
 @property (nonatomic, readonly) NSURLRequest *request;
 
index f1de404..7aeb259 100644 (file)
 
 #import <Foundation/Foundation.h>
 
-/*! WKNavigation objects are returned from the @link WKWebView @/link load methods and are passed to the 
- @link WKNavigationDelegate @/link methods. A WKNavigation object uniquely identifies a webpage load from start to finish.
+/*! A WKNavigation object contains information for tracking the loading
+ progress of a webpage.
+ @discussion A navigation is returned from the web view load methods, and is
+ also passed to the navigation delegate methods, to uniquely identify a webpage
+ load from start to finish.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKNavigation : NSObject
 
-/*! @abstract The initial NSURLRequest used to perform the navigation.
+/*! @abstract The initial request used to perform the navigation.
  */
 @property (nonatomic, readonly) NSURLRequest *initialRequest;
 
-/*! @abstract The current request of the navigation. This request may be different from the request returned by initialRequest if server side redirects have happened.
+/*! @abstract The navigation's current request.
+ @discussion This request may be different from the one returned by
+ initialRequest if server-side redirects have occurred.
  */
 @property (nonatomic, readonly) NSURLRequest *request;
 
-/* @abstract The NSURLResponse for the navigation or nil if no response has been received yet.
+/* @abstract The response to the navigation, or nil if no response has yet
+ been received.
  */
 @property (nonatomic, readonly) NSURLResponse *response;
 
-/* @abstract The error for the navigation if it failed or nil if it did not fail.
+/* @abstract The error if the navigation failed, or nil if it did not fail.
  */
 @property (nonatomic, readonly) NSError *error;
 
index c442810..2e0f705 100644 (file)
 @class WKFrameInfo;
 
 /*! @enum WKNavigationType
- @abstract the type of action that triggered a possible navigation.
- @constant WKNavigationTypeLinkActivated    A link with an href activated by the user.
+ @abstract The type of action triggering a navigation.
+ @constant WKNavigationTypeLinkActivated    A link with an href attribute was activated by the user.
  @constant WKNavigationTypeFormSubmitted    A form was submitted.
  @constant WKNavigationTypeBackForward      An item from the back-forward list was requested.
  @constant WKNavigationTypeReload           The webpage was reloaded.
- @constant WKNavigationTypeFormResubmitted  A form was resubmitted (for example by going back or forward, or reloading).
+ @constant WKNavigationTypeFormResubmitted  A form was resubmitted (for example by going back, going forward, or reloading).
  @constant WKNavigationTypeOther            Navigation is taking place for some other reason.
  */
 typedef NS_ENUM(NSInteger, WKNavigationType) {
@@ -53,24 +53,26 @@ typedef NS_ENUM(NSInteger, WKNavigationType) {
     WKNavigationTypeOther = -1,
 } WK_ENUM_AVAILABLE(10_10, 8_0);
 
-/*! Contains information about an action that may cause a navigation. Used for making policy decisions.
+/*! 
+A WKNavigationAction object contains information about an action that may cause a navigation, used for making policy decisions.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKNavigationAction : NSObject
 
-/*! @abstract Describes the frame that requested the navigation.
+/*! @abstract The frame requesting the navigation.
  */
 @property (nonatomic, readonly) WKFrameInfo *sourceFrame;
 
-/*! @abstract Describes the target frame of the navigation. If this is a new window navigation, targetFrame will be nil.
+/*! @abstract The target frame, or nil if this is a new window navigation.
  */
 @property (nonatomic, readonly) WKFrameInfo *targetFrame;
 
-/*! @abstract The type of the navigation.
+/*! @abstract The type of action that triggered the navigation.
+ @discussion The value is one of the constants of the enumerated type WKNavigationType.
  */
 @property (nonatomic, readonly) WKNavigationType navigationType;
 
-/*! @abstract The NSURLRequest of the navigation.
+/*! @abstract The navigation's request.
  */
 @property (nonatomic, readonly) NSURLRequest *request;
 
@@ -80,7 +82,7 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 @property (nonatomic, readonly) NSEventModifierFlags modifierFlags;
 
-/*! @abstract The mouse button number that caused the navigation to be requested.
+/*! @abstract The number of the mouse button causing the navigation to be requested.
  */
 @property (nonatomic, readonly) NSInteger buttonNumber;
 
index fd53197..9f4db68 100644 (file)
@@ -35,7 +35,8 @@
 @class WKWebView;
 
 /*! @enum WKNavigationActionPolicy
- @abstract the policy to pass back to the decision handler in webView:decidePolicyForNavigationAction:decisionHandler:.
+ @abstract The policy to pass back to the decision handler from the
+ webView:decidePolicyForNavigationAction:decisionHandler: method.
  @constant WKNavigationActionPolicyCancel   Cancel the navigation.
  @constant WKNavigationActionPolicyAllow    Allow the navigation to continue.
  */
@@ -45,7 +46,7 @@ typedef NS_ENUM(NSInteger, WKNavigationActionPolicy) {
 } WK_ENUM_AVAILABLE(10_10, 8_0);
 
 /*! @enum WKNavigationResponsePolicy
- @abstract the policy to pass back to the decision handler in webView:decidePolicyForNavigationResponse:decisionHandler:.
+ @abstract The policy to pass back to the decision handler from the webView:decidePolicyForNavigationResponse:decisionHandler: method.
  @constant WKNavigationResponsePolicyCancel   Cancel the navigation.
  @constant WKNavigationResponsePolicyAllow    Allow the navigation to continue.
  */
@@ -54,62 +55,71 @@ typedef NS_ENUM(NSInteger, WKNavigationResponsePolicy) {
     WKNavigationResponsePolicyAllow,
 } WK_ENUM_AVAILABLE(10_10, 8_0);
 
-/*! A class that conforms to WKNavigationDelegate can decide policy for main frame and subframe navigations,
- and track progress for main frame navigations.
+/*! A class conforming to the WKNavigationDelegate protocol can provide
+ methods for tracking progress for main frame navigations and for deciding
+ policy for main frame and subframe navigations.
  */
 @protocol WKNavigationDelegate <NSObject>
 
 @optional
 
-/*! @abstract Decides whether a navigation should be allowed or not.
- @param webView The WKWebView invoking the delegate method.
- @param navigationAction A description of the action that triggered the navigation request.
- @param decisionHandler The decision handler that should be called to allow or cancel the navigation.
+/*! @abstract Decides whether to allow or cancel a navigation.
+ @param webView The web view invoking the delegate method.
+ @param navigationAction Descriptive information about the action
+ triggering the navigation request.
+ @param decisionHandler The decision handler to call to allow or cancel the
+ navigation. The argument is one of the constants of the enumerated type WKNavigationActionPolicy.
  */
 - (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler;
 
-/*! @abstract Decides whether a navigation should be allowed or cancelled once its response is known.
- @param webView The WKWebView invoking the delegate method.
- @param navigationResponse A description of the navigation response.
- @param decisionHandler The decision handler that should be called to allow or cancel the navigation.
+/*! @abstract Decides whether to allow or cancel a navigation after its
+ response is known.
+ @param webView The web view invoking the delegate method.
+ @param navigationResponse Descriptive information about the navigation
+ response.
+ @param decisionHandler The decision handler to call to allow or cancel the
+ navigation. The argument is one of the constants of the enumerated type WKNavigationResponsePolicy.
  */
 - (void)webView:(WKWebView *)webView decidePolicyForNavigationResponse:(WKNavigationResponse *)navigationResponse decisionHandler:(void (^)(WKNavigationResponsePolicy))decisionHandler;
 
 /*! @abstract Invoked when a main frame navigation starts.
- @param webView The WKWebView invoking the delegate method.
+ @param webView The web view invoking the delegate method.
  @param navigation The navigation.
  */
 - (void)webView:(WKWebView *)webView didStartProvisionalNavigation:(WKNavigation *)navigation;
 
-/*! @abstract Invoked when a server redirect is received for the main frame.
- @param webView The WKWebView invoking the delegate method.
+/*! @abstract Invoked when a server redirect is received for the main
+ frame.
+ @param webView The web view invoking the delegate method.
  @param navigation The navigation.
  */
 - (void)webView:(WKWebView *)webView didReceiveServerRedirectForProvisionalNavigation:(WKNavigation *)navigation;
 
-/*! @abstract Invoked if an error occurs when starting to load data for the main frame.
- @param webView The WKWebView invoking the delegate method.
+/*! @abstract Invoked when an error occurs while starting to load data for
+ the main frame.
+ @param webView The web view invoking the delegate method.
  @param navigation The navigation.
- @param error Specifies the type of error that occurred during the navigation.
+ @param error The error that occurred.
  */
 - (void)webView:(WKWebView *)webView didFailProvisionalNavigation:(WKNavigation *)navigation withError:(NSError *)error;
 
 /*! @abstract Invoked when content starts arriving for the main frame.
- @param webView The WKWebView invoking the delegate method.
+ @param webView The web view invoking the delegate method.
  @param navigation The navigation.
  */
 - (void)webView:(WKWebView *)webView didCommitNavigation:(WKNavigation *)navigation;
 
 /*! @abstract Invoked when a main frame navigation completes.
- @param webView The WKWebView invoking the delegate method.
+ @param webView The web view invoking the delegate method.
  @param navigation The navigation.
  */
 - (void)webView:(WKWebView *)webView didFinishNavigation:(WKNavigation *)navigation;
 
-/*! @abstract Invoked if an error occurs while loading a committed main frame navigation.
- @param webView The WKWebView invoking the delegate method.
+/*! @abstract Invoked when an error occurs during a committed main frame
+ navigation.
+ @param webView The web view invoking the delegate method.
  @param navigation The navigation.
- @param error Specifies the type of error that occurred during the navigation.
+ @param error The error that occurred.
  */
 - (void)webView:(WKWebView *)webView didFailNavigation:(WKNavigation *)navigation withError:(NSError *)error;
 
index adc6959..6667a10 100644 (file)
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKNavigationResponse : NSObject
 
-/*! @abstract Whether the frame that is being navigated is the main frame or not.
+/*! @abstract A Boolean value indicating whether the frame being navigated is the main frame.
  */
 @property (nonatomic, readonly, getter=isForMainFrame) BOOL forMainFrame;
 
-/*! @abstract The NSURLResponse of the frame.
+/*! @abstract The frame's response.
  */
 @property (nonatomic, readonly) NSURLResponse *response;
 
-/*! @abstract Whether WebKit can show the MIME type natively or not.
+/*! @abstract A Boolean value indicating whether WebKit can display the response's MIME type natively.
+ @discussion Allowing a navigation response with a MIME type that can’t be shown will cause the navigation to fail.
  */
 @property (nonatomic, readonly) BOOL canShowMIMEType;
 
index 03796e3..f420a75 100644 (file)
 #import <CoreGraphics/CoreGraphics.h>
 #import <Foundation/Foundation.h>
 
-/*! WKPreferences encapsulates the preferences you can change for one or more WKWebViews. 
- A @link WKWebView @/link can specify which WKPreferences object it uses through its @link WKWebViewConfiguration @/link.
+/*! A WKPreferences object encapsulates the preference settings for a web
+ view. The preferences object associated with a web view is specified by
+ its web view configuration.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKPreferences : NSObject
 
-/*! @abstract Returns an initialized WKPreferences object.
+/*! @abstract Returns an initialized preferences object.
  @param userDefaultsKeyPrefix The user defaults key prefix.
- @result An initialized WKPreferences object, or nil if the object could not be initialized.
- @discussion If the userDefaultsKeyPrefix argument is non-nil, it is prepended to the keys used to store preferences
- in the user defaults database. If the argument is nil, the preferences object won't save anything to the user defaults database.
+ @result An initialized preferences object.
+ @discussion If the userDefaultsKeyPrefix parameter is not nil, it is
+ prepended to the keys used to store preferences in the user defaults
+ database. If the parameter is nil, the preferences object will not save
+ anything to the user defaults database.
  */
 - (instancetype)initWithUserDefaultsKeyPrefix:(NSString *)userDefaultsKeyPrefix WK_DESIGNATED_INITIALIZER;
 
@@ -48,43 +51,56 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 @property (nonatomic, readonly) NSString *userDefaultsKeyPrefix;
 
-/*! @abstract The minimum font size in points. Defaults to 0.
+/*! @abstract The minimum font size in points.
+ @discussion The default value is 0.
  */
 @property (nonatomic) CGFloat minimumFontSize;
 
-/*! @abstract Whether JavaScript is enabled. Defaults to YES.
+/*! @abstract A Boolean value indicating whether JavaScript is enabled.
+ @discussion The default value is YES.
  */
 @property (nonatomic, getter=isJavaScriptEnabled) BOOL javaScriptEnabled;
 
-/*! @abstract Whether JavaScript can open windows without user interaction. Defaults to NO on iOS and YES on OS X.
+/*! @abstract A Boolean value indicating whether JavaScript can open
+ windows without user interaction.
+ @discussion The default value is NO in iOS and YES in OS X.
  */
 @property (nonatomic) BOOL javaScriptCanOpenWindowsAutomatically;
 
-/*! @abstract Whether the WKWebView suppresses content rendering until it is fully loaded into memory. Defaults to NO.
+/*! @abstract A Boolean value indicating whether the web view suppresses
+ content rendering until it is fully loaded into memory.
+ @discussion The default value is NO.
  */
 @property (nonatomic) BOOL suppressesIncrementalRendering;
 
 #if TARGET_OS_IPHONE
-/*! @abstract Whether HTML5 videos play inline or use the native full-screen controller. Defaults to NO.
+/*! @abstract A Boolean value indicating whether HTML5 videos play inline
+ (YES) or use the native full-screen controller (NO).
+ @discussion The default value is NO.
  */
 @property (nonatomic) BOOL allowsInlineMediaPlayback;
 
-/*! @abstract Whether HTML5 videos can play automatically or require the user to start playing them. Defaults to YES.
+/*! @abstract A Boolean value indicating whether HTML5 videos require the
+ user to start playing them (YES) or can play automatically (NO).
+ @discussion The default value is YES.
  */
 @property (nonatomic) BOOL mediaPlaybackRequiresUserAction;
 
-/*! @abstract Whether AirPlay is allowed. Defaults to YES.
+/*! @abstract A Boolean value indicating whether AirPlay is allowed.
+ @discussion The default value is YES.
  */
 @property (nonatomic) BOOL mediaPlaybackAllowsAirPlay;
 
 #endif
 
 #if !TARGET_OS_IPHONE
-/*! @abstract Whether Java is enabled. Defaults to NO.
+/*! @abstract A Boolean value indicating whether Java is enabled.
+ @discussion The default value is YES.
  */
 @property (nonatomic, getter=isJavaEnabled) BOOL javaEnabled;
 
-/*! abstract Whether plug-ins are enabled. Defaults to NO.
+/*! @abstract A Boolean value indicating whether plug-ins are enabled.
+ @discussion The default value is YES.
  */
 @property (nonatomic, getter=arePlugInsEnabled) BOOL plugInsEnabled;
 #endif
index 016e93c..f4df603 100644 (file)
 
 #import <Foundation/Foundation.h>
 
-/*! A pool of Web Content processes.
- A @link WKWebView @/link specifies its process pool through its @link WKWebViewConfiguration @/link.
- Each WKWebView will get its own Web Content process until an implementation-defined process limit is reached; after that,
- web views with the same process pool end up sharing Web Content processes.
+/*! A WKProcessPool object represents a pool of web content processes.
+ The process pool associated with a web view is specified by its web view
+ configuration. Each web view is given its own web content process until an
+ implementation-defined process limit is reached; after that, web views
+ with the same process pool end up sharing web content processes.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKProcessPool : NSObject
index c4f3d50..a551d00 100644 (file)
 
 @class WKWebView;
 
-/*! A @link WKScriptMessage @/link object contains information about a message being sent from a webpage.
+/*! A WKScriptMessage object contains information about a message sent from
+ a webpage.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKScriptMessage : NSObject
 
-/*! @abstract The body of the message. Allowed types are NSDictionary, NSArray, NSNumber, NSNull, NSString, and NSDate. */
+/*! @abstract The body of the message.
+ @discussion Allowed types are NSNumber, NSString, NSDate, NSArray,
+ NSDictionary, and NSNull.
+ */
 @property (nonatomic, readonly) id body;
 
-/*! @abstract The web view the message is coming from. */
+/*! @abstract The web view sending the message. */
 @property (nonatomic, readonly, weak) WKWebView *webView;
 
-/*! @abstract The name of the message handler this message is being sent to. */
+/*! @abstract The name of the message handler to which the message is sent.
+ */
 @property (nonatomic, readonly) NSString *name;
 
 @end
index 3691a35..2411f0f 100644 (file)
 @class WKScriptMessage;
 @class WKUserContentController;
 
-/*! A class that conforms to WKScriptMessageHandler provides a method for recieving messages from JavaScript running in a webpage.
+/*! A class conforming to the WKScriptMessageHandler protocol provides a
+ method for receiving messages from JavaScript running in a webpage.
  */
 @protocol WKScriptMessageHandler <NSObject>
 
 @required
 
-/*! @abstract Invoked when a script message is recieved from a webpage.
- @param userContentController The WKUserContentController invoking the delegate method.
- @param message The script message being received.
+/*! @abstract Invoked when a script message is received from a webpage.
+ @param userContentController The user content controller invoking the
+ delegate method.
+ @param message The script message received.
  */
 - (void)userContentController:(WKUserContentController *)userContentController didReceiveScriptMessage:(WKScriptMessage *)message;
 
index 9e67a14..36dac7d 100644 (file)
 @class WKWebViewConfiguration;
 @class WKWindowFeatures;
 
-/*! A class that conforms to WKUIDelegate provides methods for presenting native UI on behalf of the webpage.
+/*! A class conforming to the WKUIDelegate protocol provides methods for
+ presenting native UI on behalf of a webpage.
  */
 @protocol WKUIDelegate <NSObject>
 
 @optional
 
-/*! @abstract Create a new WKWebView.
- @param webView The WKWebView invoking the delegate method.
- @param configuration The configuration that must be used when creating the new WKWebView.
- @param navigationAction The navigation action that is causing the new WKWebView to be created.
+/*! @abstract Creates a new web view.
+ @param webView The web view invoking the delegate method.
+ @param configuration The configuration to use when creating the new web
+ view.
+ @param navigationAction The navigation action causing the new web view to
+ be created.
  @param windowFeatures Window features requested by the webpage.
- @result A new WKWebView or nil.
- @discussion The WKWebView returned must be created with the specified configuration. WebKit will load the request in the returned WKWebView.
+ @result A new web view or nil.
+ @discussion The web view returned must be created with the specified configuration. WebKit will load the request in the returned web view.
  */
 - (WKWebView *)webView:(WKWebView *)webView createWebViewWithConfiguration:(WKWebViewConfiguration *)configuration forNavigationAction:(WKNavigationAction *)navigationAction windowFeatures:(WKWindowFeatures *)windowFeatures;
 
-/*! @abstract Display a JavaScript alert panel.
- @param webView The WKWebView invoking the delegate method.
+/*! @abstract Displays a JavaScript alert panel.
+ @param webView The web view invoking the delegate method.
  @param message The message to display.
- @param frame Information about the frame whose JavaScript initiated this call.
- @param completionHandler The completion handler that should get called after the alert panel has been dismissed.
- @discussion Clients should visually indicate that this panel comes from JavaScript initiated by the specified frame.
- The panel should have a single "OK" button.
+ @param frame Information about the frame whose JavaScript initiated this
+ call.
+ @param completionHandler The completion handler to call after the alert
+ panel has been dismissed.
+ @discussion Clients should visually indicate that this panel comes from
+ JavaScript initiated by the specified frame.
+ The panel should have a single OK button.
  */
 - (void)webView:(WKWebView *)webView runJavaScriptAlertPanelWithMessage:(NSString *)message initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)())completionHandler;
 
-/*! @abstract Display a JavaScript confirm panel.
- @param webView The WKWebView invoking the delegate method.
+/*! @abstract Displays a JavaScript confirm panel.
+ @param webView The web view invoking the delegate method.
  @param message The message to display.
  @param frame Information about the frame whose JavaScript initiated this call.
- @param completionHandler The completion handler that should get called after the confirm panel has been dismissed.
- Pass YES if the user chose OK, NO if the user chose Cancel.
- @discussion Clients should visually indicate that this panel comes from JavaScript initiated by the specified frame.
- The panel should have two buttons, e.g. "OK" and "Cancel".
+ @param completionHandler The completion handler to call after the confirm
+ panel has been dismissed. Pass YES if the user chose OK, NO if the user
+ chose Cancel.
+ @discussion Clients should visually indicate that this panel comes from
+ JavaScript initiated by the specified frame.
+ The panel should have two buttons, such as OK and Cancel.
  */
 - (void)webView:(WKWebView *)webView runJavaScriptConfirmPanelWithMessage:(NSString *)message initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(BOOL result))completionHandler;
 
-/*! @abstract Display a JavaScript text input panel.
- @param webView The WKWebView invoking the delegate method.
+/*! @abstract Displays a JavaScript text input panel.
+ @param webView The web view invoking the delegate method.
  @param message The message to display.
- @param defaultText The initial text for the text entry area.
+ @param defaultText The initial text to display in the text entry field.
  @param frame Information about the frame whose JavaScript initiated this call.
- @param completionHandler The completion handler that should get called after the text input panel has been dismissed. Pass the typed text if the user chose OK, otherwise nil.
- @discussion Clients should visually indicate that this panel comes from JavaScript initiated by the specified frame.
- The panel should have two buttons, e.g. "OK" and "Cancel", and an area to type text.
+ @param completionHandler The completion handler to call after the text
+ input panel has been dismissed. Pass the entered text if the user chose
+ OK, otherwise nil.
+ @discussion Clients should visually indicate that this panel comes from
+ JavaScript initiated by the specified frame.
+ The panel should have two buttons, such as OK and Cancel, and a field in
+ which to enter text.
  */
 - (void)webView:(WKWebView *)webView runJavaScriptTextInputPanelWithPrompt:(NSString *)prompt defaultText:(NSString *)defaultText initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(NSString *result))completionHandler;
 
index 477a07e..115e48a 100644 (file)
 @class WKUserScript;
 @protocol WKScriptMessageHandler;
 
-/*! WKUserContentController provides a way for JavaScript to post messages to the @link WKWebView @/link.
- A @link WKWebView @/link can specify which WKUserContentController object it uses through its @link WKWebViewConfiguration @/link.
+/*! A WKUserContentController object provides a way for JavaScript to post
+ messages to a web view.
+ The user content controller associated with a web view is specified by its
+ web view configuration.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKUserContentController : NSObject
 
-/*! @abstract The user scripts associated with this user content controller.
+/*! @abstract The user scripts associated with this user content
+ controller.
 */
 @property (nonatomic, readonly) NSArray *userScripts;
 
@@ -52,9 +55,11 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
 - (void)removeAllUserScripts;
 
 /*! @abstract Adds a script message handler.
- @param scriptMessageHandler The message handler where the messages should be delivered.
+ @param scriptMessageHandler The message handler to add.
  @param name The name of the message handler.
- @discussion Adding a scriptMessageHandler adds a function window.webkit.messageHandlers.<name>.postMessage(<messageBody>) for all frames.
+ @discussion Adding a scriptMessageHandler adds a function
+ window.webkit.messageHandlers.<name>.postMessage(<messageBody>) for all
+ frames.
  */
 - (void)addScriptMessageHandler:(id <WKScriptMessageHandler>)scriptMessageHandler name:(NSString *)name;
 
index 662a078..24be8da 100644 (file)
@@ -42,7 +42,7 @@
 @protocol WKUIDelegate;
 
 /*!
- A @link WKWebView @/link displays interactive Web content.
+ A WKWebView object displays interactive Web content.
  @helperclass @link WKWebViewConfiguration @/link
  Used to configure @link WKWebView @/link instances.
  */
@@ -54,90 +54,108 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKWebView : NSView
 #endif
 
-/*! @abstract A copy of the configuration with which the @link WKWebView @/link was initialized. */
+/*! @abstract A copy of the configuration with which the web view was
+ initialized. */
 @property (nonatomic, readonly) WKWebViewConfiguration *configuration;
 
-/*! @abstract The view's navigation delegate. */
+/*! @abstract The web view's navigation delegate. */
 @property (nonatomic, weak) id <WKNavigationDelegate> navigationDelegate;
 
-/*! @abstract The view's user interface delegate. */
+/*! @abstract The web view's user interface delegate. */
 @property (nonatomic, weak) id <WKUIDelegate> UIDelegate;
 
-/*! @abstract The view's back-forward list. */
+/*! @abstract The web view's back-forward list. */
 @property (nonatomic, readonly) WKBackForwardList *backForwardList;
 
-/*! @abstract Returns a view initialized with the specified frame and configuration.
- @param frame The frame for the new view.
- @param configuration The configuration for the new view.
- @result An initialized view, or nil if the object could not be initialized.
- @discussion This is a designated initializer. You can use @link -initWithFrame: @/link to
- initialize an instance with the default configuration.
- The initializer copies
- @link //apple_ref/doc/methodparam/WKWebView/initWithFrame:configuration:/configuration
- configuration@/link, so mutating it after initialization has no effect on the
- @link WKWebView @/link instance.
+/*! @abstract Returns a web view initialized with a specified frame and
+ configuration.
+ @param frame The frame for the new web view.
+ @param configuration The configuration for the new web view.
+ @result An initialized web view, or nil if the object could not be
+ initialized.
+ @discussion This is a designated initializer. You can use
+ @link -initWithFrame: @/link to initialize an instance with the default
+ configuration. The initializer copies the specified configuration, so
+ mutating the configuration after invoking the initializer has no effect
+ on the web view.
  */
 - (instancetype)initWithFrame:(CGRect)frame configuration:(WKWebViewConfiguration *)configuration WK_DESIGNATED_INITIALIZER;
 
-- (instancetype)initWithCoder:(NSCoder *)coder WK_UNAVAILABLE;
-
-/*! @abstract Navigates to the given NSURLRequest.
- @param request The NSURLRequest to navigate to.
+/*! @abstract Navigates to a requested URL.
+ @param request The request specifying the URL to which to navigate.
  @result A new navigation for the given request.
  */
 - (WKNavigation *)loadRequest:(NSURLRequest *)request;
 
-/*! @abstract Navigates to an item from the back-forward list and sets it as the current item.
- @param item The item to navigate to. Must be one of the items in the receiver's back-forward list.
- @result A new navigation to the requested item, or nil if it is the current item or the item is not part of the view's back-forward list.
+/*! @abstract Navigates to an item from the back-forward list and sets it
+ as the current item.
+ @param item The item to which to navigate. Must be one of the items in the
+ web view's back-forward list.
+ @result A new navigation to the requested item, or nil if it is already
+ the current item or is not part of the web view's back-forward list.
  @seealso backForwardList
  */
 - (WKNavigation *)goToBackForwardListItem:(WKBackForwardListItem *)item;
 
-/*! @abstract The webpage title. @link WKWebView @/link is KVO-compliant for this property.
+/*! @abstract The page title.
+ @discussion @link WKWebView @/link is key-value observing (KVO) compliant
+ for this property.
  */
 @property (nonatomic, readonly) NSString *title;
 
-/*! @abstract The active URL. @link WKWebView @/link is KVO-compliant for this property.
- @discussion This is the URL that should be reflected in the user interface.
+/*! @abstract The active URL.
+ @discussion This is the URL that should be reflected in the user
+ interface.
+ @link WKWebView @/link is key-value observing (KVO) compliant for this
+ property.
  */
 @property (nonatomic, readonly) NSURL *URL;
 
-/*! @abstract Whether the view is loading content. @link WKWebView @/link is KVO-compliant for this
- property. */
+/*! @abstract A Boolean value indicating whether the view is currently
+ loading content.
+ @discussion @link WKWebView @/link is key-value observing (KVO) compliant
+ for this property.
+ */
 @property (nonatomic, readonly, getter=isLoading) BOOL loading;
 
-/*! @abstract An estimate of the fraction complete for a document load. @link WKWebView @/link is
- KVO-compliant for this property.
- @discussion This value will range from 0 to 1 and, once a load completes, will remain at 1.0
- until a new load starts, at which point it will be reset to 0. The value is an estimate based
- on the total number of bytes expected to be received for a document,
- including all its possible subresources.
+/*! @abstract An estimate of what fraction of the current navigation has been completed.
+ @discussion This value ranges from 0.0 to 1.0 based on the total number of
+ bytes expected to be received, including the main document and all of its
+ potential subresources. After a navigation completes, the value remains at 1.0
+ until a new navigation starts, at which point it is reset to 0.0.
+ @link WKWebView @/link is key-value observing (KVO) compliant for this
+ property.
  */
 @property (nonatomic, readonly) double estimatedProgress;
 
-/*! @abstract Whether all of the resources on the webpage have been loaded over securely encrypted connections.
- @link WKWebView @/link is KVO-compliant for this property.
+/*! @abstract A Boolean value indicating whether all resources on the page
+ have been loaded over securely encrypted connections.
+ @discussion @link WKWebView @/link is key-value observing (KVO) compliant
+ for this property.
  */
 @property (nonatomic, readonly) BOOL hasOnlySecureContent;
 
-/*! @abstract Whether there's a back item in the back-forward list that can be navigated to.
+/*! @abstract A Boolean value indicating whether there is a back item in
+ the back-forward list that can be navigated to.
  @seealso backForwardList.
  */
 @property (nonatomic, readonly) BOOL canGoBack;
 
-/*! @abstract Whether there's a forward item in the back-forward list that can be navigated to.
+/*! @abstract A Boolean value indicating whether there is a forward item in
+ the back-forward list that can be navigated to.
  @seealso backForwardList.
  */
 @property (nonatomic, readonly) BOOL canGoForward;
 
 /*! @abstract Navigates to the back item in the back-forward list.
- @result A new navigation to the requested item, or nil if there is no back item in the back-forward list.
+ @result A new navigation to the requested item, or nil if there is no back
+ item in the back-forward list.
  */
 - (WKNavigation *)goBack;
 
 /*! @abstract Navigates to the forward item in the back-forward list.
- @result A new navigation to the requested item, or nil if there is no forward item in the back-forward list.
+ @result A new navigation to the requested item, or nil if there is no
+ forward item in the back-forward list.
  */
 - (WKNavigation *)goForward;
 
@@ -146,7 +164,8 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 - (WKNavigation *)reload;
 
-/*! @abstract Reloads the current page, performing end-to-end revalidation using cache-validating conditionals if possible.
+/*! @abstract Reloads the current page, performing end-to-end revalidation
+ using cache-validating conditionals if possible.
  @result A new navigation representing the reload.
  */
 - (WKNavigation *)reloadFromOrigin;
@@ -155,7 +174,9 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 - (void)stopLoading;
 
-/*! @abstract Whether horizontal swipe gestures will trigger back-forward list navigations. Defaults to NO.
+/*! @abstract A Boolean value indicating whether horizontal swipe gestures
+ will trigger back-forward list navigations.
+ @discussion The default value is NO.
  */
 @property (nonatomic) BOOL allowsBackForwardNavigationGestures;
 
@@ -166,17 +187,22 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
 #endif
 
 #if !TARGET_OS_IPHONE
-/* @abstract Whether magnify gestures will change the WKWebView magnification. Defaults to NO.
- @discussion It is possible to set the magnification property even if allowsMagnify is set to NO.
+/* @abstract A Boolean value indicating whether magnify gestures will
+ change the web view's magnification.
+ @discussion It is possible to set the magnification property even if
+ allowsMagnification is set to NO.
+ The default value is NO.
  */
 @property (nonatomic) BOOL allowsMagnification;
 
-/* @abstract The amount by which the webpage content is currently scaled. Defaults to 1.0.
+/* @abstract The factor by which the page content is currently scaled.
+ @discussion The default value is 1.0.
  */
 @property (nonatomic) CGFloat magnification;
 
-/* @abstract Magnify the webpage content by the given amount and center the result on the given point.
- * @param magnification The amount by which to magnify the content.
+/* @abstract Scales the page content by a specified factor and centers the
+ result on a specified point.
+ * @param magnification The factor by which to scale the content.
  * @param point The point (in view space) on which to center magnification.
  */
 - (void)setMagnification:(CGFloat)magnification centeredAtPoint:(CGPoint)point;
@@ -189,12 +215,14 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
 
 @interface WKWebView (WKIBActions) <NSUserInterfaceValidations>
 
-/*! @abstract Action method that navigates to the back item in the back-forward list.
+/*! @abstract Action method that navigates to the back item in the
+ back-forward list.
  @param sender The object that sent this message.
  */
 - (IBAction)goBack:(id)sender;
 
-/*! @abstract Action method that navigates to the forward item in the back-forward list.
+/*! @abstract Action method that navigates to the forward item in the
+ back-forward list.
  @param sender The object that sent this message.
  */
 - (IBAction)goForward:(id)sender;
@@ -204,13 +232,14 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 - (IBAction)reload:(id)sender;
 
-/*! @abstract Action method that reloads the current page, performing end-to-end revalidation using 
- cache-validating conditionals if possible.
+/*! @abstract Action method that reloads the current page, performing
end-to-end revalidation using cache-validating conditionals if possible.
  @param sender The object that sent this message.
  */
 - (IBAction)reloadFromOrigin:(id)sender;
 
-/*! @abstract Action method that stops loading all resources on the current page.
+/*! @abstract Action method that stops loading all resources on the current
+ page.
  @param sender The object that sent this message.
  */
 - (IBAction)stopLoading:(id)sender;
index 332ee17..a416f2d 100644 (file)
 @class WKProcessPool;
 @class WKUserContentController;
 
-/*! A @link WKWebViewConfiguration @/link is a collection of properties used to initialize a web
- view.
+/*! A WKWebViewConfiguration object is a collection of properties with
which to initialize a web view.
  @helps Contains properties used to configure a @link WKWebView @/link.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKWebViewConfiguration : NSObject <NSCopying>
 
-/*! @abstract The process pool from which the Web Content process for the view should come.
- @discussion When the @link WKWebView @/link is initialized with the configuration, a new Web
- Content process from the specified pool will be created for it, or an existing process in
+/*! @abstract The process pool from which to obtain the view's web content
+ process.
+ @discussion When a web view is initialized, a new web content process
+ will be created for it from the specified pool, or an existing process in
  that pool will be used.
 */
 @property (nonatomic, strong) WKProcessPool *processPool;
 
-/*! @abstract The preferences that should be used by web views created with this configuration.
+/*! @abstract The preference settings to be used by the web view.
 */
 @property (nonatomic, strong) WKPreferences *preferences;
 
-/*! @abstract The user content controller that should be used by web views created with this configuration.
+/*! @abstract The user content controller to associate with the web view.
 */
 @property (nonatomic, strong) WKUserContentController *userContentController;