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

See Also:

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

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]
Comment 2 Geoffrey Garen 2014-05-30 11:05:40 PDT
Created attachment 232297 [details]
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]

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

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>