8226765: Commentary on Javadoc comments

Reviewed-by: jjg, rhalade, skoivu, andrew

src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/JavaScriptScanner.java

@@ -69,12 +69,10 @@ public class JavaScriptScanner {
     private boolean newline = true;
 
     Map<String, TagParser> tagParsers;
-    Set<String> eventAttrs;
     Set<String> uriAttrs;
 
     public JavaScriptScanner() {
         initTagParsers();
-        initEventAttrs();
         initURIAttrs();
     }
 
@@ -101,7 +99,10 @@ public class JavaScriptScanner {
 
     private void checkHtmlAttr(String name, String value) {
         String n = name.toLowerCase(Locale.ENGLISH);
-        if (eventAttrs.contains(n)
+        // See https://www.w3.org/TR/html52/webappapis.html#events-event-handlers
+        // An event handler has a name, which always starts with "on" and is followed by
+        // the name of the event for which it is intended.
+        if (n.startsWith("on")
                 || uriAttrs.contains(n)
                     && value != null && value.toLowerCase(Locale.ENGLISH).trim().startsWith("javascript:")) {
             reporter.report();
@@ -1061,34 +1062,6 @@ public class JavaScriptScanner {
 
     }
 
-    private void initEventAttrs() {
-        eventAttrs = new HashSet<>(Arrays.asList(
-            // See https://www.w3.org/TR/html-markup/global-attributes.html#common.attrs.event-handler
-            "onabort",  "onblur",  "oncanplay",  "oncanplaythrough",
-            "onchange",  "onclick",  "oncontextmenu",  "ondblclick",
-            "ondrag",  "ondragend",  "ondragenter",  "ondragleave",
-            "ondragover",  "ondragstart",  "ondrop",  "ondurationchange",
-            "onemptied",  "onended",  "onerror",  "onfocus",  "oninput",
-            "oninvalid",  "onkeydown",  "onkeypress",  "onkeyup",
-            "onload",  "onloadeddata",  "onloadedmetadata",  "onloadstart",
-            "onmousedown",  "onmousemove",  "onmouseout",  "onmouseover",
-            "onmouseup",  "onmousewheel",  "onpause",  "onplay",
-            "onplaying",  "onprogress",  "onratechange",  "onreadystatechange",
-            "onreset",  "onscroll",  "onseeked",  "onseeking",
-            "onselect",  "onshow",  "onstalled",  "onsubmit",  "onsuspend",
-            "ontimeupdate",  "onvolumechange",  "onwaiting",
-
-            // See https://www.w3.org/TR/html4/sgml/dtd.html
-            // Most of the attributes that take a %Script are also defined as event handlers
-            // in HTML 5. The one exception is onunload.
-            // "onchange",  "onclick",   "ondblclick",  "onfocus",
-            // "onkeydown",  "onkeypress",  "onkeyup",  "onload",
-            // "onmousedown",  "onmousemove",  "onmouseout",  "onmouseover",
-            // "onmouseup",  "onreset",  "onselect",  "onsubmit",
-            "onunload"
-        ));
-    }
-
     private void initURIAttrs() {
         uriAttrs = new HashSet<>(Arrays.asList(
             // See https://www.w3.org/TR/html4/sgml/dtd.html

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/JavaScriptScanner.java

@@ -61,34 +61,8 @@ public class JavaScriptScanner extends DocTreePathScanner<Void, Consumer<DocTree
     public Void visitAttribute(AttributeTree tree, Consumer<DocTreePath> f) {
         String name = tree.getName().toString().toLowerCase(Locale.ENGLISH);
         switch (name) {
-            // See https://www.w3.org/TR/html-markup/global-attributes.html#common.attrs.event-handler
-            case "onabort":  case "onblur":  case "oncanplay":  case "oncanplaythrough":
-            case "onchange":  case "onclick":  case "oncontextmenu":  case "ondblclick":
-            case "ondrag":  case "ondragend":  case "ondragenter":  case "ondragleave":
-            case "ondragover":  case "ondragstart":  case "ondrop":  case "ondurationchange":
-            case "onemptied":  case "onended":  case "onerror":  case "onfocus":  case "oninput":
-            case "oninvalid":  case "onkeydown":  case "onkeypress":  case "onkeyup":
-            case "onload":  case "onloadeddata":  case "onloadedmetadata":  case "onloadstart":
-            case "onmousedown":  case "onmousemove":  case "onmouseout":  case "onmouseover":
-            case "onmouseup":  case "onmousewheel":  case "onpause":  case "onplay":
-            case "onplaying":  case "onprogress":  case "onratechange":  case "onreadystatechange":
-            case "onreset":  case "onscroll":  case "onseeked":  case "onseeking":
-            case "onselect":  case "onshow":  case "onstalled":  case "onsubmit":  case "onsuspend":
-            case "ontimeupdate":  case "onvolumechange":  case "onwaiting":
-
-            // See https://www.w3.org/TR/html4/sgml/dtd.html
-            // Most of the attributes that take a %Script are also defined as event handlers
-            // in HTML 5. The one exception is onunload.
-            // case "onchange":  case "onclick":   case "ondblclick":  case "onfocus":
-            // case "onkeydown":  case "onkeypress":  case "onkeyup":  case "onload":
-            // case "onmousedown":  case "onmousemove":  case "onmouseout":  case "onmouseover":
-            // case "onmouseup":  case "onreset":  case "onselect":  case "onsubmit":
-            case "onunload":
-                f.accept(getCurrentPath());
-                break;
-
             // See https://www.w3.org/TR/html4/sgml/dtd.html
-            //     https://www.w3.org/TR/html5/
+            //     https://www.w3.org/TR/html52/fullindex.html#attributes-table
             // These are all the attributes that take a %URI or a valid URL potentially surrounded
             // by spaces
             case "action":  case "cite":  case "classid":  case "codebase":  case "data":
@@ -102,6 +76,14 @@ public class JavaScriptScanner extends DocTreePathScanner<Void, Consumer<DocTree
                     }
                 }
                 break;
+            // See https://www.w3.org/TR/html52/webappapis.html#events-event-handlers
+            // An event handler has a name, which always starts with "on" and is followed by
+            // the name of the event for which it is intended.
+            default:
+                if (name.startsWith("on")) {
+                    f.accept(getCurrentPath());
+                }
+                break;
         }
         return super.visitAttribute(tree, f);
     }

test/langtools/jdk/javadoc/tool/TestScriptInComment.java

@@ -25,7 +25,7 @@
 
 /**
  * @test
- * @bug 8138725
+ * @bug 8138725 8226765
  * @summary test --allow-script-in-comments
  * @modules jdk.javadoc/jdk.javadoc.internal.tool
  */
@@ -65,6 +65,10 @@ public class TestScriptInComment {
         WS("< script >#ALERT</script>", false, "-Xdoclint:none"), // script tag with invalid white space
         SP("<script src=\"file\"> #ALERT </script>", true), // script tag with an attribute
         ON("<a onclick='#ALERT'>x</a>", true), // event handler attribute
+        OME("<img alt='1' onmouseenter='#ALERT'>", true), // onmouseenter event handler attribute
+        OML("<img alt='1' onmouseleave='#ALERT'>", true), // onmouseleave event handler attribute
+        OFI("<a href='#' onfocusin='#ALERT'>x</a>", true), // onfocusin event handler attribute
+        OBE("<a onbogusevent='#ALERT'>x</a>", true), // bogus/future event handler attribute
         URI("<a href='javascript:#ALERT'>x</a>", true); // javascript URI
 
         /**