8138725: Add options for Javadoc generation

Reviewed-by: jjg

langtools/make/build.properties

@@ -126,7 +126,8 @@ javac.tests = \
 
 javadoc.includes = \
         com/sun/javadoc/ \
-        com/sun/tools/javadoc/
+        com/sun/tools/javadoc/ \
+	com/sun/tools/doclets/internal/toolkit/util/FatalError.java
 
 javadoc.tests = \
         tools/javadoc/

langtools/src/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -27,6 +27,8 @@ package com.sun.tools.doclets.formats.html;
 
 import com.sun.tools.doclets.internal.toolkit.*;
 import com.sun.tools.doclets.internal.toolkit.util.*;
+import com.sun.tools.javadoc.JavaScriptScanner;
+import com.sun.tools.javadoc.RootDocImpl;
 
 import com.sun.javadoc.*;
 import java.util.*;
@@ -170,6 +172,11 @@ public class ConfigurationImpl extends Configuration {
      */
     public boolean createoverview = false;
 
+    /**
+     * Whether or not to check for JavaScript in doc comments.
+     */
+    private boolean allowScriptInComments;
+
     /**
      * Unique Resource Handler for this package.
      */
@@ -266,8 +273,11 @@ public class ConfigurationImpl extends Configuration {
                 nooverview = true;
             } else if (opt.equals("-overview")) {
                 overview = true;
+            } else if (opt.equals("--allow-script-in-comments")) {
+                allowScriptInComments = true;
             }
         }
+
         if (root.specifiedClasses().length > 0) {
             Map<String,PackageDoc> map = new HashMap<String,PackageDoc>();
             PackageDoc pd;
@@ -281,6 +291,30 @@ public class ConfigurationImpl extends Configuration {
         }
         setCreateOverview();
         setTopFile(root);
+
+        if (root instanceof RootDocImpl) {
+            JavaScriptScanner jss = ((RootDocImpl) root).initJavaScriptScanner(isAllowScriptInComments());
+            if (jss != null) {
+                // In a more object-oriented world, this would be done by methods on the Option objects.
+                // Note that -windowtitle silently removes any and all HTML elements, and so does not need
+                // to be handled here.
+                checkJavaScript(jss, "-header", header);
+                checkJavaScript(jss, "-footer", footer);
+                checkJavaScript(jss, "-top", top);
+                checkJavaScript(jss, "-bottom", bottom);
+                checkJavaScript(jss, "-doctitle", doctitle);
+                checkJavaScript(jss, "-packagesheader", packagesheader);
+            }
+        }
+    }
+
+    private void checkJavaScript(JavaScriptScanner jss, final String opt, String value) {
+        jss.parse(value, new JavaScriptScanner.Reporter() {
+            public void report() {
+                root.printError(getText("doclet.JavaScript_in_option", opt));
+                throw new FatalError();
+            }
+        });
     }
 
     /**
@@ -314,7 +348,8 @@ public class ConfigurationImpl extends Configuration {
             option.equals("-serialwarn") ||
             option.equals("-use") ||
             option.equals("-nonavbar") ||
-            option.equals("-nooverview")) {
+            option.equals("-nooverview") ||
+            option.equals("--allow-script-in-comments")) {
             return 1;
         } else if (option.equals("-help")) {
             System.out.println(getText("doclet.usage"));
@@ -518,4 +553,13 @@ public class ConfigurationImpl extends Configuration {
         else
             return Locale.getDefault();
     }
+
+    /**
+     * Returns whether or not to allow JavaScript in comments.
+     * Default is off; can be set true from a command line option.
+     * @return the allowScriptInComments
+     */
+    public boolean isAllowScriptInComments() {
+        return allowScriptInComments;
+    }
 }

langtools/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDoclet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -187,6 +187,8 @@ public class HtmlDoclet extends AbstractDoclet {
                 }
             } catch (IOException e) {
                 throw new DocletAbortException(e);
+            } catch (FatalError fe) {
+                throw fe;
             } catch (DocletAbortException de) {
                 throw de;
             } catch (Exception e) {

langtools/src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlWriter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -150,7 +150,11 @@ public class HtmlWriter {
 
     public final Content descfrmInterfaceLabel;
 
-    private final Writer writer;
+    private final File file;
+
+    private final String docEncoding;
+
+    private Writer writer;
 
     /**
      * Constructor.
@@ -168,8 +172,9 @@ public class HtmlWriter {
     public HtmlWriter(Configuration configuration,
                       String path, String filename, String docencoding)
                       throws IOException, UnsupportedEncodingException {
-        writer = Util.genWriter(configuration, path, filename, docencoding);
+        file = Util.genWriterFile(configuration, path, filename);
         this.configuration = configuration;
+        this.docEncoding = docencoding;
         htmlFilename = filename;
         this.memberDetailsListPrinted = false;
         packageTableHeader = new String[] {
@@ -219,6 +224,7 @@ public class HtmlWriter {
     }
 
     public void write(Content c) throws IOException {
+        writer = Util.genWriter(file, docEncoding);
         c.write(writer, true);
     }
 

langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/AbstractDoclet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2008, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -84,6 +84,8 @@ public abstract class AbstractDoclet {
         } catch (Configuration.Fault f) {
             root.printError(f.getMessage());
             return false;
+        } catch (FatalError fe) {
+            return false;
         } catch (DocletAbortException e) {
             Throwable cause = e.getCause();
             if (cause != null) {

langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AbstractBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -108,7 +108,14 @@ public abstract class AbstractBuilder {
             configuration.root.printError("Unknown element: " + component);
             throw new DocletAbortException(e);
         } catch (InvocationTargetException e) {
-            throw new DocletAbortException(e.getCause());
+            Throwable cause = e.getCause();
+            if (cause instanceof FatalError) {
+                throw (FatalError) cause;
+            } else if (cause instanceof DocletAbortException) {
+                throw (DocletAbortException) cause;
+            } else {
+                throw new DocletAbortException(cause);
+            }
         } catch (Exception e) {
             e.printStackTrace();
             configuration.root.printError("Exception " +

langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/resources/doclets.properties

@@ -30,6 +30,8 @@ doclet.Encoding_not_supported=Encoding not supported: {0}
 doclet.Building_Tree=Building tree for all the packages and classes...
 doclet.Building_Index=Building index for all the packages and classes...
 doclet.Building_Index_For_All_Classes=Building index for all classes...
+doclet.JavaScript_in_option=Argument for {0} contains JavaScript.\n\
+Use --allow-script-in-comments to allow use of JavaScript.
 doclet.sourcetab_warning=The argument for -sourcetab must be an integer greater than 0.
 doclet.Packages=Packages
 doclet.Other_Packages=Other Packages

langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/FatalError.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package com.sun.tools.doclets.internal.toolkit.util;
+
+/**
+ *  <p><b>This is NOT part of any supported API.
+ *  If you write code that depends on this, you do so at your own risk.
+ *  This code and its internal interfaces are subject to change or
+ *  deletion without notice.</b>
+ */
+@Deprecated
+public class FatalError extends Error {
+    private static final long serialVersionUID = -9131058909576418984L;
+
+    public FatalError() { }
+}

langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Util.java

@@ -646,14 +646,47 @@ public class Util {
             String path, String filename,
             String docencoding)
         throws IOException, UnsupportedEncodingException {
-        FileOutputStream fos;
+        return genWriter(genWriterFile(configuration, path, filename), docencoding);
+    }
+
+    /**
+     * Create the directory path for the file to be generated.
+     *
+     * @param path The directory path to be created for this file.
+     * @param filename File Name to which the PrintWriter will do the Output.
+     * @exception IOException Exception raised by the FileWriter is passed on
+     * to next level.
+     * @exception UnsupportedEncodingException Exception raised by the
+     * OutputStreamWriter is passed on to next level.
+     * @return the file getting generated.
+     */
+    public static File genWriterFile(Configuration configuration,
+                                     String path, String filename) {
         if (path != null) {
             DirectoryManager.createDirectory(configuration, path);
-            fos = new FileOutputStream(((path.length() > 0)?
+            return new File(((path.length() > 0)? path + File.separator: "") + filename);
-                                                  path + File.separator: "") + filename);
         } else {
-            fos = new FileOutputStream(filename);
+            return new File(filename);
         }
+    }
+
+    /**
+     * Constructs FileOutputStream and OutputStreamWriter,
+     * depending upon docencoding.
+     *
+     * @param file file to which the PrintWriter will do the Output.
+     * @param docencoding Encoding to be used for this file.
+     * @exception IOException Exception raised by the FileWriter is passed on
+     * to next level.
+     * @exception UnsupportedEncodingException Exception raised by the
+     * OutputStreamWriter is passed on to next level.
+     * @return Writer Writer for the file getting generated.
+     * @see java.io.FileOutputStream
+     * @see java.io.OutputStreamWriter
+     */
+    public static Writer genWriter(File file, String docencoding)
+        throws IOException, UnsupportedEncodingException {
+        FileOutputStream fos = new FileOutputStream(file);
         if (docencoding == null) {
             return new BufferedWriter(new OutputStreamWriter(fos));
         } else {

langtools/src/share/classes/com/sun/tools/javac/parser/JavacParser.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -434,7 +434,7 @@ public class JavacParser implements Parser {
     /**
      * Ident = IDENTIFIER
      */
-    Name ident() {
+    public Name ident() {
         if (S.token() == IDENTIFIER) {
             Name name = S.name();
             S.nextToken();

langtools/src/share/classes/com/sun/tools/javadoc/DocEnv.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -76,7 +76,7 @@ public class DocEnv {
     JavadocEnter enter;
 
     /** The name table. */
-    Names names;
+    private final Names names;
 
     /** The encoding name. */
     private String encoding;
@@ -97,6 +97,7 @@ public class DocEnv {
     Check chk;
     Types types;
     JavaFileManager fileManager;
+    JavaScriptScanner javaScriptScanner;
 
     /** Allow documenting from class files? */
     boolean docClasses = false;
@@ -767,4 +768,14 @@ public class DocEnv {
             result |= Modifier.VOLATILE;
         return result;
     }
+
+    JavaScriptScanner initJavaScriptScanner(boolean allowScriptInComments) {
+        if (allowScriptInComments) {
+            javaScriptScanner = null;
+        } else {
+            javaScriptScanner = new JavaScriptScanner();
+        }
+        return javaScriptScanner;
+    }
+
 }

langtools/src/share/classes/com/sun/tools/javadoc/DocImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -32,7 +32,7 @@ import java.text.CollationKey;
 import javax.tools.FileObject;
 
 import com.sun.javadoc.*;
-
+import com.sun.tools.doclets.internal.toolkit.util.FatalError;
 import com.sun.tools.javac.util.Position;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -102,7 +102,17 @@ public abstract class DocImpl implements Doc, Comparable<Object> {
      */
     Comment comment() {
         if (comment == null) {
-            comment = new Comment(this, documentation());
+            String d = documentation();
+            if (env.javaScriptScanner != null) {
+                env.javaScriptScanner.parse(d, new JavaScriptScanner.Reporter() {
+                    @Override
+                    public void report() {
+                        env.error(DocImpl.this, "javadoc.JavaScript_in_comment");
+                        throw new FatalError();
+                    }
+                });
+            }
+            comment = new Comment(this, d);
         }
         return comment;
     }

langtools/src/share/classes/com/sun/tools/javadoc/RootDocImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -363,4 +363,9 @@ public class RootDocImpl extends DocImpl implements RootDoc {
     public Locale getLocale() {
         return env.doclocale.locale;
     }
+
+    public JavaScriptScanner initJavaScriptScanner(boolean allowScriptInComments) {
+        return env.initJavaScriptScanner(allowScriptInComments);
+    }
+
 }

langtools/src/share/classes/com/sun/tools/javadoc/resources/javadoc.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -107,6 +107,8 @@ javadoc.File_Read_Error=Error while reading file {0}
 javadoc.Body_missing_from_html_file=Body tag missing from HTML file
 javadoc.End_body_missing_from_html_file=Close body tag missing from HTML file
 javadoc.Multiple_package_comments=Multiple sources of package comments found for package "{0}"
+javadoc.JavaScript_in_comment=JavaScript found in documentation comment.\n\
+    Use --allow-script-in-comments to allow use of JavaScript.
 javadoc.class_not_found=Class {0} not found.
 javadoc.error=error
 javadoc.warning=warning