Some proof-reading of the WebKit2 API headerdoc
authorggaren@apple.com <ggaren@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Wed, 28 May 2014 00:16:25 +0000 (00:16 +0000)
committerggaren@apple.com <ggaren@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Wed, 28 May 2014 00:16:25 +0000 (00:16 +0000)
https://bugs.webkit.org/show_bug.cgi?id=133328

Reviewed by Anders Carlsson.

Consistently say "item" to reference back-forward list items.

Consistently say "webpage" instead of "page" or "web page".

Consistently say "navigation" instead of "load".

Plus a few fix-ups for run-on sentences, mismatched verb tense, and
mismatched singular vs plural.

* UIProcess/API/Cocoa/WKBackForwardList.h:
* UIProcess/API/Cocoa/WKBackForwardListItem.h:
* UIProcess/API/Cocoa/WKBrowsingContextController.h:
* UIProcess/API/Cocoa/WKBrowsingContextGroup.h:
* UIProcess/API/Cocoa/WKFrameInfo.h:
* UIProcess/API/Cocoa/WKNavigation.h:
* UIProcess/API/Cocoa/WKNavigationAction.h:
* UIProcess/API/Cocoa/WKNavigationDelegate.h:
* UIProcess/API/Cocoa/WKProcessPool.h:
* UIProcess/API/Cocoa/WKUIDelegate.h:
* UIProcess/API/Cocoa/WKWebView.h:

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

15 files changed:
Source/WebKit2/ChangeLog
Source/WebKit2/UIProcess/API/Cocoa/WKBackForwardList.h
Source/WebKit2/UIProcess/API/Cocoa/WKBackForwardListItem.h
Source/WebKit2/UIProcess/API/Cocoa/WKBrowsingContextController.h
Source/WebKit2/UIProcess/API/Cocoa/WKBrowsingContextGroup.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/WKProcessPool.h
Source/WebKit2/UIProcess/API/Cocoa/WKScriptMessage.h
Source/WebKit2/UIProcess/API/Cocoa/WKScriptMessageHandler.h
Source/WebKit2/UIProcess/API/Cocoa/WKUserScript.h
Source/WebKit2/UIProcess/API/Cocoa/WKWebView.h
Source/WebKit2/UIProcess/API/mac/WKView.mm

index fa0b7b6..fa54b86 100644 (file)
@@ -1,3 +1,31 @@
+2014-05-27  Geoffrey Garen  <ggaren@apple.com>
+
+        Some proof-reading of the WebKit2 API headerdoc
+        https://bugs.webkit.org/show_bug.cgi?id=133328
+
+        Reviewed by Anders Carlsson.
+
+        Consistently say "item" to reference back-forward list items.
+
+        Consistently say "webpage" instead of "page" or "web page".
+
+        Consistently say "navigation" instead of "load".
+
+        Plus a few fix-ups for run-on sentences, mismatched verb tense, and
+        mismatched singular vs plural.
+
+        * UIProcess/API/Cocoa/WKBackForwardList.h:
+        * UIProcess/API/Cocoa/WKBackForwardListItem.h:
+        * UIProcess/API/Cocoa/WKBrowsingContextController.h:
+        * UIProcess/API/Cocoa/WKBrowsingContextGroup.h:
+        * UIProcess/API/Cocoa/WKFrameInfo.h:
+        * UIProcess/API/Cocoa/WKNavigation.h:
+        * UIProcess/API/Cocoa/WKNavigationAction.h:
+        * UIProcess/API/Cocoa/WKNavigationDelegate.h:
+        * UIProcess/API/Cocoa/WKProcessPool.h:
+        * UIProcess/API/Cocoa/WKUIDelegate.h:
+        * UIProcess/API/Cocoa/WKWebView.h:
+
 2014-05-27  Timothy Horton  <timothy_horton@apple.com>
 
         [wk2] PDFPlugin snapshots are misplaced
index 56cd4db..efaac55 100644 (file)
@@ -47,18 +47,18 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 @property (nonatomic, readonly) WKBackForwardListItem *forwardItem;
 
-/*! @abstract Returns an entry the given distance from the current entry.
+/*! @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 entry the given distance from the current entry. If index exceeds the limits of the list, nil is returned.
+ @result The item the given distance from the current item. If index exceeds the limits of the list, nil is returned.
  */
 - (WKBackForwardListItem *)itemAtIndex:(NSInteger)index;
 
-/*! @abstract Returns the portion of the list before the current entry.
+/*! @abstract Returns the portion of the list before the current item.
  @discussion The entries are in the order that they were originally visited.
  */
 @property (nonatomic, readonly) NSArray *backList;
 
-/*! @abstract Returns the portion of the list after the current entry.
+/*! @abstract Returns the portion of the list after the current item.
  @discussion The entries are in the order that they were originally visited.
  */
 @property (nonatomic, readonly) NSArray *forwardList;
index 84a43c1..b5e2985 100644 (file)
 
 #import <Foundation/Foundation.h>
 
-/*! A @link WKBackForwardListItem @/link represents a visited page in a WKWebView's back-forward list.
+/*! A @link WKBackForwardListItem @/link represents a visited webpage in a WKWebView's back-forward list.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKBackForwardListItem : NSObject
 
-/*! @abstract The URL of the page represented by this item.
+/*! @abstract The URL of the webpage represented by this item.
  */
 @property (readonly) NSURL *URL;
 
-/*! @abstract The title of the page represented by this item.
+/*! @abstract The title of the webpage represented by this item.
  */
 @property (readonly) NSString *title;
 
-/*! @abstract The URL of the navigation that created this item.
+/*! @abstract The URL of the initial request that created this item.
  */
 @property (readonly) NSURL *initialURL;
 
index 636cedd..424f53f 100644 (file)
@@ -64,13 +64,13 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
 - (void)loadFileURL:(NSURL *)URL restrictToFilesWithin:(NSURL *)allowedDirectory;
 - (void)loadFileURL:(NSURL *)URL restrictToFilesWithin:(NSURL *)allowedDirectory userData:(id)userData;
 
-/* Load a page using the passed in string as its contents. */
+/* Load a webpage using the passed in string as its contents. */
 - (void)loadHTMLString:(NSString *)HTMLString baseURL:(NSURL *)baseURL;
 - (void)loadHTMLString:(NSString *)HTMLString baseURL:(NSURL *)baseURL userData:(id)userData;
 
 - (void)loadAlternateHTMLString:(NSString *)string baseURL:(NSURL *)baseURL forUnreachableURL:(NSURL *)unreachableURL;
 
-/* Load a page using the passed in data as its contents. */
+/* Load a webpage using the passed in data as its contents. */
 - (void)loadData:(NSData *)data MIMEType:(NSString *)MIMEType textEncodingName:(NSString *)encodingName baseURL:(NSURL *)baseURL;
 - (void)loadData:(NSData *)data MIMEType:(NSString *)MIMEType textEncodingName:(NSString *)encodingName baseURL:(NSURL *)baseURL userData:(id)userData;
 
@@ -88,16 +88,16 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
 
 #pragma mark Back/Forward
 
-/* Go to the next page in the back/forward list. */
+/* Go to the next webpage in the back/forward list. */
 - (void)goForward;
 
-/* Whether there is a next page in the back/forward list. */
+/* Whether there is a next webpage in the back/forward list. */
 @property(readonly) BOOL canGoForward;
 
-/* Go to the previous page in the back/forward list. */
+/* Go to the previous webpage in the back/forward list. */
 - (void)goBack;
 
-/* Whether there is a previous page in the back/forward list. */
+/* Whether there is a previous webpage in the back/forward list. */
 @property(readonly) BOOL canGoBack;
 
 - (void)goToBackForwardListItem:(WKBackForwardListItem *)item;
index 5d15118..cd3b04d 100644 (file)
@@ -46,7 +46,7 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
 
 /* Settings */
 
-/* Setting to control whether JavaScript referenced by a page is enabled.
+/* Setting to control whether JavaScript is enabled.
    Default: YES
 */
 @property BOOL allowsJavaScript;
index 5433b6c..c311b60 100644 (file)
@@ -29,9 +29,9 @@
 
 #import <Foundation/Foundation.h>
 
-/*! A @link WKFrameInfo @/link object contains information about a frame on a web page.
- @discussion WKFrameInfo objects are transient data only objects, they can not be used to uniquely 
- identify a frame across multiple delegate method calls.
+/*! 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.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKFrameInfo : NSObject
index 979112f..f1de404 100644 (file)
@@ -29,8 +29,8 @@
 
 #import <Foundation/Foundation.h>
 
-/*! WKNavigation objects are returned from  the @link WKWebView @/link load methods and are passed to the 
- @link WKNavigationDelegate @/link methods, and can be used to track page loads from start to finish.
+/*! 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.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKNavigation : NSObject
@@ -47,7 +47,7 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 @property (nonatomic, readonly) NSURLResponse *response;
 
-/* @abstract The page load error if the page failed to load, nil otherwise.
+/* @abstract The error for the navigation if it failed or nil if it did not fail.
  */
 @property (nonatomic, readonly) NSError *error;
 
index 030699a..c442810 100644 (file)
@@ -40,8 +40,8 @@
  @constant WKNavigationTypeLinkActivated    A link with an href activated by the user.
  @constant WKNavigationTypeFormSubmitted    A form was submitted.
  @constant WKNavigationTypeBackForward      An item from the back-forward list was requested.
- @constant WKNavigationTypeReload           The page was reloaded.
- @constant WKNavigationTypeFormResubmitted  A form was resubmitted (for example by going back, forward or reloading).
+ @constant WKNavigationTypeReload           The webpage was reloaded.
+ @constant WKNavigationTypeFormResubmitted  A form was resubmitted (for example by going back or forward, or reloading).
  @constant WKNavigationTypeOther            Navigation is taking place for some other reason.
  */
 typedef NS_ENUM(NSInteger, WKNavigationType) {
@@ -53,16 +53,16 @@ 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.
+/*! 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 Represents the frame that is requesting the navigation.
+/*! @abstract Describes the frame that requested the navigation.
  */
 @property (nonatomic, readonly) WKFrameInfo *sourceFrame;
 
-/*! @abstract Represents the target frame. If this is a new window navigation, targetFrame will be nil.
+/*! @abstract Describes the target frame of the navigation. If this is a new window navigation, targetFrame will be nil.
  */
 @property (nonatomic, readonly) WKFrameInfo *targetFrame;
 
index 33abb6f..fd53197 100644 (file)
@@ -54,8 +54,8 @@ typedef NS_ENUM(NSInteger, WKNavigationResponsePolicy) {
     WKNavigationResponsePolicyAllow,
 } WK_ENUM_AVAILABLE(10_10, 8_0);
 
-/*! A class that conforms to WKNavigationDelegate can provide methods for deciding load policy for main frame and subframe loads
- and track load progress for main frame loads.
+/*! A class that conforms to WKNavigationDelegate can decide policy for main frame and subframe navigations,
+ and track progress for main frame navigations.
  */
 @protocol WKNavigationDelegate <NSObject>
 
@@ -64,18 +64,18 @@ typedef NS_ENUM(NSInteger, WKNavigationResponsePolicy) {
 /*! @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 load.
+ @param decisionHandler The decision handler that should be called to allow or cancel the navigation.
  */
 - (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 load.
+ @param decisionHandler The decision handler that should be called to allow or cancel the navigation.
  */
 - (void)webView:(WKWebView *)webView decidePolicyForNavigationResponse:(WKNavigationResponse *)navigationResponse decisionHandler:(void (^)(WKNavigationResponsePolicy))decisionHandler;
 
-/*! @abstract Invoked when a main frame page load starts.
+/*! @abstract Invoked when a main frame navigation starts.
  @param webView The WKWebView invoking the delegate method.
  @param navigation The navigation.
  */
@@ -90,7 +90,7 @@ typedef NS_ENUM(NSInteger, WKNavigationResponsePolicy) {
 /*! @abstract Invoked if an error occurs when starting to load data for the main frame.
  @param webView The WKWebView invoking the delegate method.
  @param navigation The navigation.
- @param error Specifies the type of error that occurred during the load.
+ @param error Specifies the type of error that occurred during the navigation.
  */
 - (void)webView:(WKWebView *)webView didFailProvisionalNavigation:(WKNavigation *)navigation withError:(NSError *)error;
 
@@ -100,16 +100,16 @@ typedef NS_ENUM(NSInteger, WKNavigationResponsePolicy) {
  */
 - (void)webView:(WKWebView *)webView didCommitNavigation:(WKNavigation *)navigation;
 
-/*! @abstract Invoked when a main frame load completes.
+/*! @abstract Invoked when a main frame navigation completes.
  @param webView The WKWebView invoking the delegate method.
  @param navigation The navigation.
  */
 - (void)webView:(WKWebView *)webView didFinishNavigation:(WKNavigation *)navigation;
 
-/*! @abstract Invoked if an error occurs loading a committed main frame page load.
+/*! @abstract Invoked if an error occurs while loading a committed main frame navigation.
  @param webView The WKWebView invoking the delegate method.
  @param navigation The navigation.
- @param error Specifies the type of error that occurred during the load.
+ @param error Specifies the type of error that occurred during the navigation.
  */
 - (void)webView:(WKWebView *)webView didFailNavigation:(WKNavigation *)navigation withError:(NSError *)error;
 
index d08de03..016e93c 100644 (file)
@@ -30,7 +30,7 @@
 #import <Foundation/Foundation.h>
 
 /*! A pool of Web Content processes.
- A @link WKWebView @/link specifies from which pool the Web Content process backing it comes through its @link WKWebViewConfiguration @/link.
+ 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.
  */
index 15adce8..c4f3d50 100644 (file)
@@ -31,7 +31,7 @@
 
 @class WKWebView;
 
-/*! A @link WKScriptMessage @/link object contains information about a message being sent from a web page.
+/*! A @link WKScriptMessage @/link object contains information about a message being sent from a webpage.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKScriptMessage : NSObject
index 556b800..3691a35 100644 (file)
 @class WKScriptMessage;
 @class WKUserContentController;
 
-/*! A class that conforms to WKScriptMessageHandler provides a method for recieving messages from JavaScript running in a web page.
+/*! A class that conforms to WKScriptMessageHandler provides a method for recieving messages from JavaScript running in a webpage.
  */
 @protocol WKScriptMessageHandler <NSObject>
 
 @required
 
-/*! @abstract Invoked when a script message is recieved from a web page.
+/*! @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.
  */
index 7481488..39a7338 100644 (file)
@@ -30,7 +30,7 @@
 #import <Foundation/Foundation.h>
 
 /*! @enum WKUserScriptInjectionTime
- @abstract when a user script should be injected into a web page.
+ @abstract when a user script should be injected into a webpage.
  @constant WKUserScriptInjectionTimeAtDocumentStart    Inject the script after the document element has been created, but before any other content has been loaded.
  @constant WKUserScriptInjectionTimeAtDocumentEnd      Inject the script after the document has finished loading, but before any subresources may have finished loading.
  */
@@ -39,7 +39,7 @@ typedef NS_ENUM(NSInteger, WKUserScriptInjectionTime) {
     WKUserScriptInjectionTimeAtDocumentEnd
 } WK_ENUM_AVAILABLE(10_10, 8_0);
 
-/*! A @link WKUserScript @/link object represents a script that can be injected into web pages.
+/*! A @link WKUserScript @/link object represents a script that can be injected into webpages.
  */
 WK_CLASS_AVAILABLE(10_10, 8_0)
 @interface WKUserScript : NSObject <NSCopying>
index be39039..662a078 100644 (file)
@@ -94,7 +94,7 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 - (WKNavigation *)goToBackForwardListItem:(WKBackForwardListItem *)item;
 
-/*! @abstract The page title. @link WKWebView @/link is KVO-compliant for this property.
+/*! @abstract The webpage title. @link WKWebView @/link is KVO-compliant for this property.
  */
 @property (nonatomic, readonly) NSString *title;
 
@@ -116,7 +116,7 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 @property (nonatomic, readonly) double estimatedProgress;
 
-/*! @abstract Whether all of the resources on the page have been loaded over securely encrypted connections.
+/*! @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.
  */
 @property (nonatomic, readonly) BOOL hasOnlySecureContent;
@@ -171,11 +171,11 @@ WK_CLASS_AVAILABLE(10_10, 8_0)
  */
 @property (nonatomic) BOOL allowsMagnification;
 
-/* @abstract The amount by which the page content is currently scaled. Defaults to 1.0.
+/* @abstract The amount by which the webpage content is currently scaled. Defaults to 1.0.
  */
 @property (nonatomic) CGFloat magnification;
 
-/* @abstract Magnify the page content by the given amount and center the result on the given point.
+/* @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.
  * @param point The point (in view space) on which to center magnification.
  */
index b811feb..00f0912 100644 (file)
@@ -1700,7 +1700,7 @@ static void extractUnderlines(NSAttributedString *string, Vector<CompositionUnde
     [self _disableComplexTextInputIfNecessary];
 
     // Pass key combos through WebCore if there is a key binding available for
-    // this event. This lets web pages have a crack at intercepting key-modified keypresses.
+    // this event. This lets webpages have a crack at intercepting key-modified keypresses.
     // FIXME: Why is the firstResponder check needed?
     if (self == [[self window] firstResponder]) {
         [self _interpretKeyEvent:event completionHandler:^(BOOL handledByInputMethod, const Vector<KeypressCommand>& commands) {
@@ -2131,7 +2131,7 @@ static void extractUnderlines(NSAttributedString *string, Vector<CompositionUnde
     [self _disableComplexTextInputIfNecessary];
 
     // Pass key combos through WebCore if there is a key binding available for
-    // this event. This lets web pages have a crack at intercepting key-modified keypresses.
+    // this event. This lets webpages have a crack at intercepting key-modified keypresses.
     // FIXME: Why is the firstResponder check needed?
     if (self == [[self window] firstResponder]) {
         Vector<KeypressCommand> commands;