Bug 35861 – [Qt] Add documentation to the QtWebkit bridge

• Component: New Bugs
• Status: CLOSED FIXED

[Noam Rosenthal]

Currently the QtWebkit bridge features are not documented, or are very sparsely documented.

[Noam Rosenthal]

Created attachment 50212 [details]
WIP: documentation for the QtWebkit bridge

[Richard Moore]

The section on security should be changed:

'such exposure should be balanced by limiting the web page's access, for example, to https-based secure sites only.'

This is bad advice since https does not guarantee that the end point is not malicious (anyone can get an https cert since it merely proves who they are). Better advice would be to tell people to ensure they trust the endpoint.

[Noam Rosenthal]

Richard Moore: thanks! my oversight.

[Noam Rosenthal]

Created attachment 54478 [details]
documentation for the QtWebkit bridge

[Noam Rosenthal]

Created attachment 54479 [details]
generated HTML documentation

to generate this yourself, go to WebKitBuild/Release, and run "make docs"

[WebKit Review Bot]

Attachment 54478 [details] did not pass style-queue:

Failed to run "['WebKitTools/Scripts/check-webkit-style', '--no-squash']" exit_code: 1
Last 3072 characters of output:
ebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:7:  Declaration has space between type name and * in QWebFrame *frame  [whitespace/declaration] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:10:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:12:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:13:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:18:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:19:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:19:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:21:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:35:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:36:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:37:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:41:  Place brace on its own line for function definitions.  [whitespace/braces] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:50:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:51:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:52:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:65:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:66:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:67:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:71:  Place brace on its own line for function definitions.  [whitespace/braces] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:80:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:81:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
Total errors found: 22 in 4 files


If any of these errors are false positives, please file a bug against check-webkit-style.

[Noam Rosenthal]

style checker should ignore those snippet files.

[Simon Hausmann]

Comment on attachment 54478 [details]
documentation for the QtWebkit bridge

Here's a first batch of comments:

WebKit/qt/docs/qtwebkit-bridge.qdoc:11
 +      \l{Qt Object Model}, which has a natural alignment to the way JavaScript worked.
worked = works.

The second sentence has a lot of buzz words :). I wonder if would make sense to simplify it a bit. How about "It uses QObject introspection, which makes it easy to integrate with the dynamic JavaScript environment." ?

WebKit/qt/docs/qtwebkit-bridge.qdoc:14
 +      pair under one name.
How about: "For example QObject properties map directly to JavaScript properties".

WebKit/qt/docs/qtwebkit-bridge.qdoc:18
 +      There are two main use cases for the QtWebKit bridge. Web content in a native application, and Thin Client.
Client or Client_s_?

WebKit/qt/docs/qtwebkit-bridge.qdoc:23
 +      applications. For example, an application that contains both a media-player, playlist manager, and
I _think_ the last comma in the line is not needed (not 100% sure, not native speaker myself :)

WebKit/qt/docs/qtwebkit-bridge.qdoc:41
 +      An example for such client is a UI for a video-on-demand service on a TV. The entire content and
such client -> such a client

WebKit/qt/docs/qtwebkit-bridge.qdoc:70
 +      To enable web content access to a native QObject, the application has to explicitly grant it access,
grant it access -> grant access? (not 100% sure)

WebKit/qt/docs/qtwebkit-bridge.qdoc:79
 +      Qt Script adapts Qt's central \l{Signals and Slots} feature for
Is it intentional to mention Qt Script here?

[Noam Rosenthal]

Being that I'm not a native English speaker myself, maybe somebody else should look at this / edit the English.
Any comments about the actual content?

[Noam Rosenthal]

Created attachment 57558 [details]
Updated patch, reviewed by our doc team

[Noam Rosenthal]

Created attachment 57559 [details]
New generated doc

[Kenneth Rohde Christiansen]

Comment on attachment 57558 [details]
Updated patch, reviewed by our doc team

What is going on here? This is not a doc change!

[Noam Rosenthal]

Created attachment 57566 [details]
oops, uploaded the wrong file

[WebKit Review Bot]

Attachment 57566 [details] did not pass style-queue:

Failed to run "['WebKitTools/Scripts/check-webkit-style', '--no-squash']" exit_code: 1
Last 3072 characters of output:
ebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:7:  Declaration has space between type name and * in QWebFrame *frame  [whitespace/declaration] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:10:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:12:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:13:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:18:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:19:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:19:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:21:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:35:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:36:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:37:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:41:  Place brace on its own line for function definitions.  [whitespace/braces] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:50:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:51:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:52:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:65:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:66:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:67:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:71:  Place brace on its own line for function definitions.  [whitespace/braces] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:80:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:81:  Weird number of spaces at line-start.  Are you using a 4-space indent?  [whitespace/indent] [3]
Total errors found: 22 in 4 files


If any of these errors are false positives, please file a bug against check-webkit-style.

[Noam Rosenthal]

How can we remove those doc files from the style-check?

[WebKit Commit Bot]

Comment on attachment 57566 [details]
oops, uploaded the wrong file

Clearing flags on attachment: 57566

Committed r60537: <http://trac.webkit.org/changeset/60537>

[WebKit Commit Bot]

All reviewed patches have been landed.  Closing bug.

[Simon Hausmann]

Revision r60537 cherry-picked into qtwebkit-2.0 with commit 56c648fdede16be00fd0040fc1cdff63ac33140b

[Noam Rosenthal]

The wrong patch sneaked in, 100% my fault. Working to amend.

[Noam Rosenthal]

Created attachment 58526 [details]
A patch that amends the state to the correct documentation

Uploaded a diff between the correct patch (which generates attachment 57559 [details]) and the patch that was accepted.

[WebKit Review Bot]

Attachment 58526 [details] did not pass style-queue:

Failed to run "['WebKitTools/Scripts/check-webkit-style', '--no-squash']" exit_code: 1
Last 3072 characters of output:
  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:126:  Place brace on its own line for function definitions.  [whitespace/braces] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:126:  Extra space before ( in function call  [whitespace/parens] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:129:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:130:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:132:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:133:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:134:  One space before end of line comments  [whitespace/comments] [5]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:136:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:137:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:138:  One space before end of line comments  [whitespace/comments] [5]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:140:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:141:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:143:  This { should be at the end of the previous line  [whitespace/braces] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:152:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:153:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:155:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:156:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:162:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:163:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:169:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:170:  Should have a space between // and comment  [whitespace/comments] [4]
WebKit/qt/docs/webkitsnippets/qtwebkit_bridge_snippets.cpp:174:  Should have a space between // and comment  [whitespace/comments] [4]
Total errors found: 59 in 3 files


If any of these errors are false positives, please file a bug against check-webkit-style.

[WebKit Commit Bot]

Comment on attachment 58526 [details]
A patch that amends the state to the correct documentation

Clearing flags on attachment: 58526

Committed r61058: <http://trac.webkit.org/changeset/61058>

[WebKit Commit Bot]

All reviewed patches have been landed.  Closing bug.

[Simon Hausmann]

Revision r61058 cherry-picked into qtwebkit-2.0 with commit f4d68eb5e73b75d4f35f375a9563433df8229973