Bug 133408 - Some more copy-editing of the Modern WebKit headerdoc
Summary: Some more copy-editing of the Modern WebKit headerdoc
Status: RESOLVED FIXED
Alias: None
Product: WebKit
Classification: Unclassified
Component: New Bugs (show other bugs)
Version: 528+ (Nightly build)
Hardware: Unspecified Unspecified
: P2 Normal
Assignee: Geoffrey Garen
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2014-05-30 10:46 PDT by Geoffrey Garen
Modified: 2014-05-30 14:41 PDT (History)
5 users (show)

See Also:

Attachments
Patch (46.59 KB, patch)
2014-05-30 10:48 PDT, Geoffrey Garen 		no flags Details | Formatted Diff | Diff
Patch (46.57 KB, patch)
2014-05-30 11:05 PDT, Geoffrey Garen 		bdakin: review+
Details | Formatted Diff | Diff
Show Obsolete (1) View All Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Geoffrey Garen 2014-05-30 10:46:11 PDT 
Some more copy-editing of the Modern WebKit headerdoc
Comment 1 Geoffrey Garen 2014-05-30 10:48:28 PDT 
Created attachment 232296 [details]
Patch
Comment 2 Geoffrey Garen 2014-05-30 11:05:40 PDT 
Created attachment 232297 [details]
Patch
Comment 3 Geoffrey Garen 2014-05-30 11:06:02 PDT 
Removed non-ASCII characters.
Comment 4 Beth Dakin 2014-05-30 11:48:36 PDT 
Comment on attachment 232297 [details]
Patch

Very nice!
Comment 5 Darin Adler 2014-05-30 11:54:49 PDT 
Comment on attachment 232297 [details]
Patch

View in context: https://bugs.webkit.org/attachment.cgi?id=232297&action=review

> Source/WebKit2/UIProcess/API/Cocoa/WKBackForwardListItem.h:32
> -/*! 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.

Not sure this is perfectly accurate. Is the page you are currently on a previously visited webpage?

> Source/WebKit2/UIProcess/API/Cocoa/WKFrameInfo.h:41
> +/*! @abstract A Boolean value indicating whether the frame is the main frame
> + or a subframe.

Are we capitalizing the word “boolean” here because of its origin as a person’s name? I suggest “boolean” with a lowercase b.

> Source/WebKit2/UIProcess/API/Cocoa/WKUIDelegate.h:76
> + @discussion Clients should visually indicate that this panel comes from
> + JavaScript initiated by the specified frame.

I think this is confusing wording. The point here is that for good security it's important to indicate that the panel comes from JavaScript and which website controls the content of the panel. But “initiated by the specified frame” is an oblique way to say this.
Comment 6 Geoffrey Garen 2014-05-30 12:11:10 PDT 
I'll address Darin's comments in a follow-up.
Comment 7 Geoffrey Garen 2014-05-30 12:12:12 PDT 
Committed r169490: <http://trac.webkit.org/changeset/169490>
Comment 8 Geoffrey Garen 2014-05-30 14:08:09 PDT 
Reverted r169490 for reason:

It broke the build with a mysterious warning about ASCII

Committed r169493: <http://trac.webkit.org/changeset/169493>
Comment 9 Geoffrey Garen 2014-05-30 14:41:37 PDT 
Committed r169495: <http://trac.webkit.org/changeset/169495>