[SCM] WebKit Debian packaging branch, debian/unstable, updated. debian/1.1.15-1-40151-g37bb677

[cblu]

The following commit has been merged in the debian/unstable branch:
commit 5fb3e0a9a031a4b856933bab0b5991fa83584401
Author: cblu <cblu at 268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Date:   Mon Apr 28 01:10:49 2003 +0000

    	Improved headerdoc comments.
    
            * Misc.subproj/WebKitErrors.h:
            * WebView.subproj/WebFrameLoadDelegate.h:
    
    
    git-svn-id: http://svn.webkit.org/repository/webkit/trunk@4199 268f45cc-cd09-0410-ab3c-d52691b4dbfc

diff --git a/WebKit/ChangeLog b/WebKit/ChangeLog
index dc2fe49..8ae3f0d 100644
--- a/WebKit/ChangeLog
+++ b/WebKit/ChangeLog
@@ -1,3 +1,10 @@
+2003-04-27  Chris Blumenberg  <cblu at apple.com>
+
+	Improved headerdoc comments.	
+
+        * Misc.subproj/WebKitErrors.h:
+        * WebView.subproj/WebFrameLoadDelegate.h:
+
 2003-04-25  Don Melton  <gramps at apple.com>
 
 	Backed out Richard's (hopefully) accidental checkin of our experiments
diff --git a/WebKit/Misc.subproj/WebKitErrors.h b/WebKit/Misc.subproj/WebKitErrors.h
index b167d69..15d6ddf 100644
--- a/WebKit/Misc.subproj/WebKitErrors.h
+++ b/WebKit/Misc.subproj/WebKitErrors.h
@@ -13,7 +13,7 @@ extern NSString * const WebKitErrorPlugInPageURLStringKey;
 
 /*!
     @enum
-    @description Policy errors
+    @abstract Policy errors
     @constant WebKitErrorCannotShowMIMEType
     @constant WebKitErrorCannotShowURL
     @constant WebKitErrorFrameLoadInterruptedByPolicyChange
@@ -26,7 +26,7 @@ enum {
 
 /*!
     @enum
-    @description Plug-in and java errors
+    @abstract Plug-in and java errors
     @constant WebKitErrorCannotFindPlugin
     @constant WebKitErrorCannotLoadPlugin
     @constant WebKitErrorJavaUnavailable
diff --git a/WebKit/WebView.subproj/WebFrameLoadDelegate.h b/WebKit/WebView.subproj/WebFrameLoadDelegate.h
index 05f3550..6cdde1e 100644
--- a/WebKit/WebView.subproj/WebFrameLoadDelegate.h
+++ b/WebKit/WebView.subproj/WebFrameLoadDelegate.h
@@ -13,46 +13,49 @@
 
 /*!
     @category WebFrameLoadDelegate
-    @discussion A WebView's WebFrameLoadDelegate tracks changes to its frames' location(s). 
+    @discussion A WebView's WebFrameLoadDelegate tracks the loading progress of its frames.
+    When a data source of a frame starts to load, the data source is considered "provisional".
+    Once at least one byte is received, the data source is considered "committed". This is done
+    so the contents of the frame will not be lost if the new data source fails to successfully load.
 */
 @interface NSObject (WebFrameLoadDelegate)
 
 /*!
     @method webView:didStartProvisionalLoadForFrame:
-    @abstract Notifies the delegate that the provisional data source on the frame has started to load.
+    @abstract Notifies the delegate that the provisional load of a frame has started
     @param webView The WebView sending the message
     @param frame The frame for which the provisional load has started
+    @discussion This method is called after the provisional data source of a frame
+    has started to load.
 */
 - (void)webView:(WebView *)sender didStartProvisionalLoadForFrame:(WebFrame *)frame;
 
 /*!
     @method webView:didReceiveServerRedirectForProvisionalLoadForFrame:
-    @abstract Notifies the delegate that the provisional data source has received a server redirect.
+    @abstract Notifies the delegate that a server redirect occurred during the provisional load
     @param webView The WebView sending the message
-    @param frame The data source for which the redirect occurred
+    @param frame The frame for which the redirect occurred
 */
 - (void)webView:(WebView *)sender didReceiveServerRedirectForProvisionalLoadForFrame:(WebFrame *)frame;
 
 /*!
     @method webView:didFailProvisionalLoadWithError:forFrame:
-    @abstract Notifies the delegate that the provisional load has failed.
+    @abstract Notifies the delegate that the provisional load has failed
     @param webView The WebView sending the message
     @param error The error that occurred
-    @param frame The data source for which the error occurred
-    @discussion When webView:didFailProvisionalLoadWithError:forFrame: is called the provisional data source
-    has failed to load. The frame will continue to display the committed data source if there is one.
+    @param frame The frame for which the error occurred
+    @discussion This method is called after the provisional data source has failed to load.
+    The frame will continue to display the contents of the committed data source if there is one.
 */
 - (void)webView:(WebView *)sender didFailProvisionalLoadWithError:(NSError *)error forFrame:(WebFrame *)frame;
 
 /*!
     @method webView:didCommitLoadForFrame:
-    @abstract Notifies the delegate that the load has changed from provisional to committed.
+    @abstract Notifies the delegate that the load has changed from provisional to committed
     @param webView The WebView sending the message
     @param frame The frame for which the load has committed
-    @discussion When a load starts, it is considered
-    "provisional" until at least one byte of the new page is
-    received. This is done so the old page will not be lost if the new
-    page fails to load completely.
+    @discussion This method is called after the provisional data source has become the
+    committed data source.
 
     In some cases, a single load may be committed more than once. This happens
     in the case of multipart/x-mixed-replace, also known as "server push". In this case,
@@ -63,39 +66,41 @@
 
 /*!
     @method webView:didReceiveTitle:forFrame:
-    @abstract Notify that the page title has been determined or has changed
+    @abstract Notifies the delegate that the page title for a frame has been received
     @param webView The WebView sending the message
     @param title The new page title
-    @param frame The frame for which the title changed
+    @param frame The frame for which the title has been received
     @discussion The title may update during loading; clients should be prepared for this.
 */
 - (void)webView:(WebView *)sender didReceiveTitle:(NSString *)title forFrame:(WebFrame *)frame;
 
 /*!
     @method webView:didReceiveIcon:forFrame:
-    @abstract Notifies the delegate that a page icon image has been received
+    @abstract Notifies the delegate that a page icon image for a frame has been received
     @param webView The WebView sending the message
-    @param image The icon image
+    @param image The icon image. Also known as a "favicon".
     @param frame The frame for which a page icon has been received
 */
 - (void)webView:(WebView *)sender didReceiveIcon:(NSImage *)image forFrame:(WebFrame *)frame;
 
 /*!
     @method webView:didFinishLoadForFrame:
-    @abstract Notifies the delegate that the load is done
+    @abstract Notifies the delegate that the committed load of a frame has completed
     @param webView The WebView sending the message
     @param frame The frame that finished loading
-    @discussion This callback will only be received when all subresources are done loading.
+    @discussion This method is called after the committed data source of a frame has successfully loaded
+    and will only be called when all subresources such as images and stylesheets are done loading.
+    Plug-In content and JavaScript-requested loads may occur after this method is called.
 */
 - (void)webView:(WebView *)sender didFinishLoadForFrame:(WebFrame *)frame;
 
 /*!
     @method webView:didFailLoadWithError:forFrame:
-    @abstract Notifies the delegate that the committed load has failed
+    @abstract Notifies the delegate that the committed load of a frame has failed
     @param webView The WebView sending the message
     @param error The error that occurred
     @param frame The frame that failed to load
-    @discussion This method is called after the load has commmitted but ended in error.
+    @discussion This method is called after a data source has committed but failed to completely load.
 */
 - (void)webView:(WebView *)sender didFailLoadWithError:(NSError *)error forFrame:(WebFrame *)frame;
 
@@ -104,32 +109,29 @@
     @abstract Notifies the delegate that the scroll position in a frame has changed
     @param webView The WebView sending the message
     @param frame The frame that scrolled
-    @discussion This is normally used for clicks on anchors within a page
-    that is already displayed. You can find the new URL from the data source object.
+    @discussion This method is called when anchors within a page have been clicked.
 */
 - (void)webView:(WebView *)sender didChangeLocationWithinPageForFrame:(WebFrame *)frame;
 
 /*!
     @method webView:willPerformClientRedirectToURL:delay:fireDate:forFrame:
-    @abstract Notifies the delegate that the frame has received a client-side redirect that may trigger soon
-    @param webView The WebView sending the message.
+    @abstract Notifies the delegate that a frame will perform a client-side redirect
+    @param webView The WebView sending the message
     @param URL The URL to be redirected to
     @param seconds Seconds in which the redirect will happen
     @param date The fire date
     @param frame The frame on which the redirect will occur
-    @discussion This method can be used to keep progress feedback
-    going while a client redirect is pending. A client redirect might
-    be cancelled before it fires - see webView:didCancelClientRedirectForFrame:.
+    @discussion This method can be used to continue progress feedback while a client-side
+    redirect is pending.
 */
 - (void)webView:(WebView *)sender willPerformClientRedirectToURL:(NSURL *)URL delay:(NSTimeInterval)seconds fireDate:(NSDate *)date forFrame:(WebFrame *)frame;
 
 /*!
-    method webView:didCancelClientRedirectForFrame:
-    @abstract Notifies the delegate that a pending client redirect has been cancelled.
-    @param webView The WebView sending the message.
+    @method webView:didCancelClientRedirectForFrame:
+    @abstract Notifies the delegate that a pending client-side redirect has been cancelled
+    @param webView The WebView sending the message
     @param frame The frame for which the pending redirect was cancelled
-    @discussion A client redirect can be cancelled if the frame
-    changes locations before the timeout.
+    @discussion A client-side redirect can be cancelled if a frame changes location before the timeout.
 */
 - (void)webView:(WebView *)sender didCancelClientRedirectForFrame:(WebFrame *)frame;
 
@@ -138,7 +140,7 @@
     @abstract Notifies the delegate that a frame will be closed
     @param webView The WebView sending the message
     @param frame The frame that will be closed
-    @discussion This callback happens right before WebKit is done with the frame
+    @discussion This method is called right before WebKit is done with the frame
     and the objects that it contains.
 */
 - (void)webView:(WebView *)sender willCloseFrame:(WebFrame *)frame;

-- 
WebKit Debian packaging