changeset 47921:6b1311fbbaba

8190819: Merge HtmlWriter into HtmlDocument Reviewed-by: bpatel, ksrini
author jjg
date Thu, 16 Nov 2017 15:12:13 -0800
parents 7640bc1eb94f
children 0e38db7cf1cc
files src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FrameOutputWriter.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/DocType.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocWriter.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocument.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlWriter.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Script.java test/langtools/jdk/javadoc/doclet/testHtmlDocument/TestHtmlDocument.java
diffstat 11 files changed, 100 insertions(+), 234 deletions(-) [+]
line wrap: on
line diff
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java	Thu Nov 16 15:12:13 2017 -0800
@@ -28,6 +28,7 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+import jdk.javadoc.internal.doclets.formats.html.markup.Comment;
 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
 import jdk.javadoc.internal.doclets.formats.html.markup.FixedStringContent;
 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
@@ -137,6 +138,7 @@
     public final Content navProperty;
     public final Content navServices;
     public final Content nestedClassSummary;
+    public final Content newPage;
     public final Content nextClassLabel;
     public final Content nextLabel;
     public final Content nextLetter;
@@ -269,6 +271,7 @@
         navProperty = getContent("doclet.navProperty");
         navServices = getContent("doclet.navServices");
         nestedClassSummary = getContent("doclet.Nested_Class_Summary");
+        newPage = new Comment(resources.getText("doclet.New_Page"));
         nextClassLabel = getNonBreakContent("doclet.Next_Class");
         nextLabel = getNonBreakContent("doclet.Next");
         nextLetter = getContent("doclet.Next_Letter");
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FrameOutputWriter.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FrameOutputWriter.java	Thu Nov 16 15:12:13 2017 -0800
@@ -34,6 +34,7 @@
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
 import jdk.javadoc.internal.doclets.formats.html.markup.Script;
 import jdk.javadoc.internal.doclets.toolkit.Content;
+import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
@@ -127,10 +128,8 @@
      * @throws DocFileIOException if there is an error writing the frames document
      */
     private void printFramesDocument(String title, HtmlTree body) throws DocFileIOException {
-        Content htmlDocType = configuration.isOutputHtml5()
-                ? DocType.HTML5
-                : DocType.TRANSITIONAL;
-        Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
+        DocType htmlDocType = DocType.forVersion(configuration.htmlVersion);
+        Content htmlComment = contents.newPage;
         Content head = new HtmlTree(HtmlTag.HEAD);
         head.addContent(getGeneratedBy(!configuration.notimestamp));
         Content windowTitle = HtmlTree.TITLE(title);
@@ -139,12 +138,11 @@
         head.addContent(meta);
         addStyleSheetProperties(configuration, head);
         head.addContent(getFramesScript().asContent());
-        Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
-                head, body);
-        Content htmlDocument = new HtmlDocument(htmlDocType,
-                htmlComment, htmlTree);
-        write(htmlDocument);
-    }
+
+        Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(), head, body);
+        HtmlDocument htmlDocument = new HtmlDocument(htmlDocType, htmlComment, htmlTree);
+        htmlDocument.write(DocFile.createFileForOutput(configuration, path));
+   }
 
     /**
      * Get the frame sizes and their contents.
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java	Thu Nov 16 15:12:13 2017 -0800
@@ -410,10 +410,8 @@
      */
     public void printHtmlDocument(List<String> metakeywords, boolean includeScript,
             Content body) throws DocFileIOException {
-        Content htmlDocType = configuration.isOutputHtml5()
-                ? DocType.HTML5
-                : DocType.TRANSITIONAL;
-        Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
+        DocType htmlDocType = DocType.forVersion(configuration.htmlVersion);
+        Content htmlComment = contents.newPage;
         Content head = new HtmlTree(HtmlTag.HEAD);
         head.addContent(getGeneratedBy(!configuration.notimestamp));
         head.addContent(HtmlTree.TITLE(winTitle));
@@ -434,11 +432,10 @@
         }
         addStyleSheetProperties(head);
         addScriptProperties(head);
-        Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
-                head, body);
-        Content htmlDocument = new HtmlDocument(htmlDocType,
-                htmlComment, htmlTree);
-        write(htmlDocument);
+
+        Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(), head, body);
+        HtmlDocument htmlDocument = new HtmlDocument(htmlDocType, htmlComment, htmlTree);
+        htmlDocument.write(DocFile.createFileForOutput(configuration, path));
     }
 
     /**
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java	Thu Nov 16 15:12:13 2017 -0800
@@ -35,6 +35,7 @@
 import jdk.javadoc.internal.doclets.formats.html.markup.Script;
 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
 import jdk.javadoc.internal.doclets.toolkit.Content;
+import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
@@ -65,10 +66,8 @@
      * @throws DocFileIOException if there is a problem generating the file
      */
     void generateIndexFile() throws DocFileIOException {
-        Content htmlDocType = configuration.isOutputHtml5()
-                ? DocType.HTML5
-                : DocType.TRANSITIONAL;
-        Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
+        DocType htmlDocType = DocType.forVersion(configuration.htmlVersion);
+        Content htmlComment = contents.newPage;
         Content head = new HtmlTree(HtmlTag.HEAD);
         head.addContent(getGeneratedBy(!configuration.notimestamp));
 
@@ -111,11 +110,8 @@
             body.addContent(bodyContent);
         }
 
-        Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
-                head, body);
-        Content htmlDocument = new HtmlDocument(htmlDocType,
-                htmlComment, htmlTree);
-        write(htmlDocument);
-
+        Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(), head, body);
+        HtmlDocument htmlDocument = new HtmlDocument(htmlDocType, htmlComment, htmlTree);
+        htmlDocument.write(DocFile.createFileForOutput(configuration, path));
     }
 }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java	Thu Nov 16 15:12:13 2017 -0800
@@ -208,23 +208,15 @@
      * @param path the path for the file.
      */
     private void writeToFile(Content body, DocPath path) throws DocFileIOException {
-        Content htmlDocType = configuration.isOutputHtml5()
-                ? DocType.HTML5
-                : DocType.TRANSITIONAL;
+        DocType htmlDocType = DocType.forVersion(configuration.htmlVersion);
         Content head = new HtmlTree(HtmlTag.HEAD);
         head.addContent(HtmlTree.TITLE(resources.getText("doclet.Window_Source_title")));
         addStyleSheetProperties(head);
         Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
                 head, body);
-        Content htmlDocument = new HtmlDocument(htmlDocType, htmlTree);
+        HtmlDocument htmlDocument = new HtmlDocument(htmlDocType, htmlTree);
         messages.notice("doclet.Generating_0", path.getPath());
-        DocFile df = DocFile.createFileForOutput(configuration, path);
-        try (Writer w = df.openWriter()) {
-            htmlDocument.write(w, true);
-        } catch (IOException e) {
-            throw new DocFileIOException(df, DocFileIOException.Mode.WRITE, e);
-        }
-
+        htmlDocument.write(DocFile.createFileForOutput(configuration, path));
     }
 
     /**
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/DocType.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/DocType.java	Thu Nov 16 15:12:13 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2017, 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
@@ -25,14 +25,8 @@
 
 package jdk.javadoc.internal.doclets.formats.html.markup;
 
-import java.io.IOException;
-import java.io.Writer;
-
-import jdk.javadoc.internal.doclets.toolkit.Content;
-import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
-
 /**
- * Class for generating document type for HTML pages of javadoc output.
+ *  Supported DOCTYPE declarations.
  *
  *  <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.
@@ -41,67 +35,22 @@
  *
  * @author Bhavesh Patel
  */
-public class DocType extends Content {
+public enum DocType {
+    HTML4_TRANSITIONAL("<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\" "
+            + "\"http://www.w3.org/TR/html4/loose.dtd\">"),
+    HTML5("<!DOCTYPE HTML>");
 
-    private String docType;
+    public final String text;
 
-    public static final DocType TRANSITIONAL =
-            new DocType("Transitional", "http://www.w3.org/TR/html4/loose.dtd");
-
-    public static final DocType HTML5 = new DocType();
-
-    /**
-     * Constructor to construct a DocType object.
-     *
-     * @param type the doctype to be added
-     * @param dtd the dtd of the doctype
-     */
-    private DocType(String type, String dtd) {
-        docType = "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 " + type +
-                "//EN\" \"" + dtd + "\">" + DocletConstants.NL;
+    DocType(String text) {
+        this.text = text;
     }
 
-    /**
-     * Constructor to construct a DocType object.
-     */
-    private DocType() {
-        docType = "<!DOCTYPE HTML>" + DocletConstants.NL;
-    }
-
-    /**
-     * This method is not supported by the class.
-     *
-     * @param content content that needs to be added
-     * @throws UnsupportedOperationException always
-     */
-    public void addContent(Content content) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * This method is not supported by the class.
-     *
-     * @param stringContent string content that needs to be added
-     * @throws UnsupportedOperationException always
-     */
-    @Override
-    public void addContent(CharSequence stringContent) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * {@inheritDoc}
-     */
-    public boolean isEmpty() {
-        return (docType.length() == 0);
-    }
-
-    /**
-     * {@inheritDoc}
-     */
-    @Override
-    public boolean write(Writer out, boolean atNewline) throws IOException {
-        out.write(docType);
-        return true; // guaranteed by constructor
+    public static DocType forVersion(HtmlVersion v) {
+        switch (v) {
+            case HTML4: return HTML4_TRANSITIONAL;
+            case HTML5: return HTML5;
+            default: throw new IllegalArgumentException();
+        }
     }
 }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocWriter.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocWriter.java	Thu Nov 16 15:12:13 2017 -0800
@@ -54,7 +54,7 @@
  * @author Atul M Dambalkar
  * @author Robert Field
  */
-public abstract class HtmlDocWriter extends HtmlWriter {
+public abstract class HtmlDocWriter {
 
     public static final String CONTENT_TYPE = "text/html";
 
@@ -62,14 +62,12 @@
     private final DocPath pathToRoot;
 
     /**
-     * Constructor. Initializes the destination file name through the super
-     * class HtmlWriter.
+     * Constructor.
      *
      * @param configuration the configuration for this doclet
-     * @param filename String file name.
+     * @param filename the path for the output file
      */
     public HtmlDocWriter(HtmlConfiguration configuration, DocPath filename) {
-        super(configuration, filename);
         this.configuration = configuration;
         this.pathToRoot = filename.parent().invert();
         Messages messages = configuration.getMessages();
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocument.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocument.java	Thu Nov 16 15:12:13 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2017, 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
@@ -26,10 +26,14 @@
 package jdk.javadoc.internal.doclets.formats.html.markup;
 
 import java.io.IOException;
+import java.io.StringWriter;
 import java.io.Writer;
 import java.util.*;
 
 import jdk.javadoc.internal.doclets.toolkit.Content;
+import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
+import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
+import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
 
 /**
  * Class for generating an HTML document for javadoc output.
@@ -41,9 +45,9 @@
  *
  * @author Bhavesh Patel
  */
-public class HtmlDocument extends Content {
-
-    private List<Content> docContent = Collections.emptyList();
+public class HtmlDocument {
+    private final DocType docType;
+    private final List<Content> docContent;
 
     /**
      * Constructor to construct an HTML document.
@@ -52,11 +56,9 @@
      * @param docComment comment for the document
      * @param htmlTree HTML tree of the document
      */
-    public HtmlDocument(Content docType, Content docComment, Content htmlTree) {
-        docContent = new ArrayList<>();
-        addContent(nullCheck(docType));
-        addContent(nullCheck(docComment));
-        addContent(nullCheck(htmlTree));
+    public HtmlDocument(DocType docType, Content docComment, Content htmlTree) {
+        this.docType = docType;
+        docContent = Arrays.asList(docComment, htmlTree);
     }
 
     /**
@@ -65,46 +67,41 @@
      * @param docType document type for the HTML document
      * @param htmlTree HTML tree of the document
      */
-    public HtmlDocument(Content docType, Content htmlTree) {
-        docContent = new ArrayList<>();
-        addContent(nullCheck(docType));
-        addContent(nullCheck(htmlTree));
+    public HtmlDocument(DocType docType, Content htmlTree) {
+        this.docType = docType;
+        docContent = Collections.singletonList(htmlTree);
     }
 
     /**
-     * Adds content for the HTML document.
+     * Writes the content of this document to the specified file.
      *
-     * @param htmlContent html content to be added
+     * @param docFile the file
+     * @throws DocFileIOException if an {@code IOException} occurs while writing the file
      */
-    public final void addContent(Content htmlContent) {
-        if (htmlContent.isValid())
-            docContent.add(htmlContent);
+    public void write(DocFile docFile) throws DocFileIOException {
+        try (Writer writer = docFile.openWriter()) {
+            write(writer);
+        } catch (IOException e) {
+            throw new DocFileIOException(docFile, DocFileIOException.Mode.WRITE, e);
+        }
     }
 
-    /**
-     * This method is not supported by the class.
-     *
-     * @param stringContent string content that needs to be added
-     * @throws UnsupportedOperationException always
-     */
     @Override
-    public void addContent(CharSequence stringContent) {
-        throw new UnsupportedOperationException();
+    public String toString() {
+        try (Writer writer = new StringWriter()) {
+            write(writer);
+            return writer.toString();
+        } catch (IOException e) {
+            throw new Error(e);
+        }
     }
 
-    /**
-     * {@inheritDoc}
-     */
-    public boolean isEmpty() {
-        return (docContent.isEmpty());
-    }
-
-    /**
-     * {@inheritDoc}
-     */
-    public boolean write(Writer out,  boolean atNewline) throws IOException {
-        for (Content c : docContent)
-            atNewline = c.write(out, atNewline);
-        return atNewline;
+    private void write(Writer writer) throws IOException {
+        writer.write(docType.text);
+        writer.write(DocletConstants.NL);
+        boolean atNewline = true;
+        for (Content c : docContent) {
+            atNewline = c.write(writer, atNewline);
+        }
     }
 }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlWriter.java	Thu Nov 16 15:06:17 2017 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,72 +0,0 @@
-/*
- * Copyright (c) 1997, 2017, 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 jdk.javadoc.internal.doclets.formats.html.markup;
-
-import java.io.*;
-
-import jdk.javadoc.internal.doclets.formats.html.HtmlConfiguration;
-import jdk.javadoc.internal.doclets.toolkit.Content;
-import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
-import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
-import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
-
-
-/**
- * Class for the HTML format code generation.
- * Initializes PrintWriter with FileWriter, to enable print
- * related methods to generate the code to the named File through FileWriter.
- *
- *  <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>
- *
- * @author Atul M Dambalkar
- * @author Bhavesh Patel (Modified)
- */
-public class HtmlWriter {
-
-    private final DocFile docFile;
-
-    /**
-     * Constructor.
-     *
-     * @param configuration the configuration
-     * @param path the directory path to be created for this file,
-     *             or null if none to be created
-     */
-    public HtmlWriter(HtmlConfiguration configuration, DocPath path) {
-        docFile = DocFile.createFileForOutput(configuration, path);
-    }
-
-    public void write(Content c) throws DocFileIOException {
-        try (Writer writer = docFile.openWriter()) {
-            c.write(writer, true);
-        } catch (IOException e) {
-            throw new DocFileIOException(docFile, DocFileIOException.Mode.WRITE, e);
-        }
-    }
-}
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Script.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Script.java	Thu Nov 16 15:12:13 2017 -0800
@@ -60,7 +60,7 @@
     }
 
     /**
-     * Appends the given code to the content.
+     * Appends the given code to the script.
      *
      * @param code the code
      * @return this object
@@ -71,7 +71,7 @@
     }
 
     /**
-     * Appends the given text as a string constant to the content.
+     * Appends the given text as a string constant to the string.
      * Characters within the string will be escaped as needed.
      *
      * @param text the text
@@ -83,7 +83,7 @@
     }
 
     /**
-     * Appends the given text as a string constant to the content.
+     * Appends the given text as a string constant to the string.
      * Characters within the string will be escaped as needed.
      *
      * @param text the text
@@ -98,6 +98,12 @@
         return this;
     }
 
+    /**
+     * Returns a "live" view of the script as a {@code Content} object.
+     * Any later modifications to the script will be reflected in the
+     * object that is returned.
+     * @return the script, as a {@code Content} object.
+     */
     public Content asContent() {
         ScriptContent scriptContent = new ScriptContent(sb);
         HtmlTree tree = new HtmlTree(HtmlTag.SCRIPT) {
@@ -119,21 +125,23 @@
     }
 
     /**
-     * Returns a String with escaped special JavaScript characters.
+     * Returns a JavaScript string literal containing a specified string,
+     * escaping the characters of that string as needed.
      *
-     * @param s String that needs to be escaped
-     * @return a valid escaped JavaScript string
+     * @param s the string
+     * @return a string literal containing the string
      */
     public static String stringLiteral(CharSequence s) {
         return stringLiteral(s, '"');
     }
 
     /**
-     * Returns a String with escaped special JavaScript characters.
+     * Returns a JavaScript string literal containing a specified string,
+     * escaping the characters of that string as needed.
      *
-     * @param s String that needs to be escaped
+     * @param s the string
      * @param quoteChar the quote character to use for the literal
-     * @return a valid escaped JavaScript string
+     * @return a string literal containing the string
      */
     // The ability to specify the quote character is for backwards
     // compatibility. Ideally, we should simplify the code so that
--- a/test/langtools/jdk/javadoc/doclet/testHtmlDocument/TestHtmlDocument.java	Thu Nov 16 15:06:17 2017 -0800
+++ b/test/langtools/jdk/javadoc/doclet/testHtmlDocument/TestHtmlDocument.java	Thu Nov 16 15:12:13 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2017, 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
@@ -69,7 +69,7 @@
     // Generate the HTML output using the HTML document generation within doclet.
     public static String generateHtmlTree() {
         // Document type for the HTML document
-        DocType htmlDocType = DocType.TRANSITIONAL;
+        DocType htmlDocType = DocType.HTML4_TRANSITIONAL;
         HtmlTree html = new HtmlTree(HtmlTag.HTML);
         HtmlTree head = new HtmlTree(HtmlTag.HEAD);
         HtmlTree title = new HtmlTree(HtmlTag.TITLE);