openjdk/jdk7u
1
0
Fork 0
mirror of https://github.com/openjdk/jdk7u.git synced 2025-12-10 10:13:47 -06:00
Code Issues Packages Projects Releases Wiki Activity

8138725: Add options for Javadoc generation

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Aleksei Efimov 2017-01-18 18:30:54 +00:00
parent 19fdede371
commit 4beda5cb8c
15 changed files with 1290 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
langtools/make/build.properties
View File

@ -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/

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

@ -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;
}
}

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

@ -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) {

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

@ -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);
}

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

@ -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) {

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

@ -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 " +

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

@ -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

39
langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/FatalError.java Normal file
View File

@ -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() { }
}

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

@ -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)?
path + File.separator: "") + filename);
return new File(((path.length() > 0)? 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 {

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

@ -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();

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

@ -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;
}
}

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

@ -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;
}

1103
langtools/src/share/classes/com/sun/tools/javadoc/JavaScriptScanner.java Normal file
View File

File diff suppressed because it is too large Load Diff

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

@ -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);
}
}

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

@ -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