WebUI: Provide more explicit guidance on AllowJavascript.

Bug: 750867
Change-Id: I5d2a8093123ba7cd60010f5597c5fbaf3a193188
Reviewed-on: https://chromium-review.googlesource.com/594937Reviewed-by: Demetrios Papadopoulos <dpapad@chromium.org>
Reviewed-by: Jochen Eisinger <jochen@chromium.org>
Commit-Queue: Tommy Li <tommycli@chromium.org>
Cr-Commit-Position: refs/heads/master@{#491401}

content/public/browser/web_ui_message_handler.h

@@ -47,8 +47,17 @@ class CONTENT_EXPORT WebUIMessageHandler {
   FRIEND_TEST_ALL_PREFIXES(WebUIMessageHandlerTest, ExtractDoubleValue);
   FRIEND_TEST_ALL_PREFIXES(WebUIMessageHandlerTest, ExtractStringValue);
 
-  // Subclasses must call this once the page is ready for JavaScript calls
-  // from this handler.
+  // This method must be called once the handler's corresponding JavaScript
+  // component is initialized. In practice, it should be called from a WebUI
+  // message handler similar to: 'initializeFooPage' or 'getInitialState'.
+  //
+  // There should be ideally one or two calls to this per handler, as JavaScript
+  // components should have a specific message that signals that it's initalized
+  // and ready to receive events from the C++ handler.
+  //
+  // This should never be called from a function that is not a message handler.
+  // This should never be called from a C++ callback used as a reply for a
+  // posted task or asynchronous operation.
   void AllowJavascript();
 
   // Helper methods: