stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8157349: Missing doc-files in javadoc documentation

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Kumar Srinivasan 2016-08-29 07:46:37 -07:00
parent bbf85261aa
commit 2df08320de
12 changed files with 405 additions and 63 deletions
langtools
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit
AbstractDoclet.javaWorkArounds.java
builders
ModuleSummaryBuilder.java
util
Utils.java
test/jdk/javadoc/doclet/testCopyFiles
TestCopyFiles.java
modules/acme.mdle
module-info.java
p
Foo.java
doc-files
inpackage.html
packages/p1
Foo.java
doc-files
inpackage.html
unnamed
Foo.java
doc-files
inpackage.html

1
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java

@ -204,7 +204,6 @@ public abstract class AbstractDoclet implements Doclet {
ClassTree classtree = new ClassTree(configuration, configuration.nodeprecated);
generateClassFiles(docEnv, classtree);
configuration.utils.copyDocFiles(DocPaths.DOC_FILES);
PackageListWriter.generate(configuration);
generatePackageFiles(classtree);

10
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java

@ -44,6 +44,7 @@ import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
import javax.lang.model.type.TypeMirror;
import javax.lang.model.util.Elements;
import javax.tools.JavaFileManager.Location;
import javax.tools.JavaFileObject;
import com.sun.source.tree.CompilationUnitTree;
@ -57,6 +58,7 @@ import com.sun.tools.javac.code.Scope;
import com.sun.tools.javac.code.Symbol;
import com.sun.tools.javac.code.Symbol.ClassSymbol;
import com.sun.tools.javac.code.Symbol.MethodSymbol;
import com.sun.tools.javac.code.Symbol.ModuleSymbol;
import com.sun.tools.javac.code.Symbol.VarSymbol;
import com.sun.tools.javac.comp.AttrContext;
import com.sun.tools.javac.comp.Env;
@ -289,6 +291,14 @@ public class WorkArounds {
return ((DocEnvImpl)(configuration.docEnv)).etable.shouldDocument(e);
}
// TODO: jx.l.m ?
public Location getLocationForModule(ModuleElement mdle) {
ModuleSymbol msym = (ModuleSymbol)mdle;
return msym.sourceLocation != null
? msym.sourceLocation
: msym.classLocation;
}
//------------------Start of Serializable Implementation---------------------//
private final static Map<TypeElement, NewSerializedForm> serializedForms = new HashMap<>();

6
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ModuleSummaryBuilder.java

@ -135,11 +135,7 @@ public class ModuleSummaryBuilder extends AbstractBuilder {
buildChildren(node, contentTree);
moduleWriter.addModuleFooter(contentTree);
moduleWriter.printDocument(contentTree);
// TEMPORARY:
// The use of SOURCE_PATH on the next line is temporary. As we transition into the
// modules world, this should migrate into using a location for the appropriate module
// on the MODULE_SOURCE_PATH, or (in the old doclet) simply deleted.
utils.copyDocFiles(configuration, StandardLocation.SOURCE_PATH, DocPaths.moduleSummary(mdle));
utils.copyDirectory(mdle, DocPaths.moduleSummary(mdle));
}
/**

125
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java

@ -25,6 +25,7 @@
package jdk.javadoc.internal.doclets.toolkit.util;
import java.io.IOException;
import java.lang.annotation.Documented;
import java.lang.ref.SoftReference;
import java.text.CollationKey;
@ -60,6 +61,7 @@ import javax.lang.model.util.SimpleTypeVisitor9;
import javax.lang.model.util.TypeKindVisitor9;
import javax.lang.model.util.Types;
import javax.tools.FileObject;
import javax.tools.JavaFileManager;
import javax.tools.JavaFileManager.Location;
import javax.tools.StandardLocation;
@ -77,7 +79,9 @@ import com.sun.tools.javac.util.DefinedBy;
import com.sun.tools.javac.util.DefinedBy.Api;
import jdk.javadoc.internal.doclets.toolkit.CommentUtils.DocCommentDuo;
import jdk.javadoc.internal.doclets.toolkit.Configuration;
import jdk.javadoc.internal.doclets.toolkit.DocletException;
import jdk.javadoc.internal.doclets.toolkit.Messages;
import jdk.javadoc.internal.doclets.toolkit.Resources;
import jdk.javadoc.internal.doclets.toolkit.WorkArounds;
import static javax.lang.model.element.ElementKind.*;
@ -265,29 +269,63 @@ public class Utils {
}
/**
* Copy the given directory contents from the source package directory
* to the generated documentation directory. For example for a package
* java.lang this method find out the source location of the package using
* {@link SourcePath} and if given directory is found in the source
* directory structure, copy the entire directory, to the generated
* documentation hierarchy.
* Copy doc-files directory and its contents from the source
* package directory to the generated documentation directory.
* For example, given a package java.lang, this method will copy
* the doc-files directory, found in the package directory to the
* generated documentation hierarchy.
*
* @param pe the package containing the doc files to be copied
* @throws DocFileIOException if there is a problem while copying the documentation files
* @throws DocFileIOException if there is a problem while copying
* the documentation files
*/
public void copyDocFiles(PackageElement pe) throws DocFileIOException {
copyDocFiles(DocPath.forPackage(pe).resolve(DocPaths.DOC_FILES));
Location sourceLoc = getLocationForPackage(pe);
copyDirectory(sourceLoc, DocPath.forPackage(pe).resolve(DocPaths.DOC_FILES));
}
/**
* This method is obsolete, should not be used, and should be deleted.
* It does not take module locations into account!
* Copy the given directory contents from the source package directory
* to the generated documentation directory. For example, given a package
* java.lang, this method will copy the entire directory, to the generated
* documentation hierarchy.
*
* @throws DocFileIOException if there is a problem while copying the documentation files
* @param pe the package containing the directory to be copied
* @param dir the directory to be copied
* @throws DocFileIOException if there is a problem while copying
* the documentation files
*/
public void copyDocFiles(DocPath dir) throws DocFileIOException {
public void copyDirectory(PackageElement pe, DocPath dir) throws DocFileIOException {
copyDirectory(getLocationForPackage(pe), dir);
}
/**
* Copy the given directory and its contents from the source
* module directory to the generated documentation directory.
* For example, given a package java.lang, this method will
* copy the entire directory, to the generated documentation
* hierarchy.
*
* @param mdle the module containing the directory to be copied
* @param dir the directory to be copied
* @throws DocFileIOException if there is a problem while copying
* the documentation files
*/
public void copyDirectory(ModuleElement mdle, DocPath dir) throws DocFileIOException {
copyDirectory(getLocationForModule(mdle), dir);
}
/**
* Copy files from a doc path location to the output.
*
* @param locn the location from which to read files
* @param dir the directory to be copied
* @throws DocFileIOException if there is a problem
* copying the files
*/
public void copyDirectory(Location locn, DocPath dir) throws DocFileIOException {
boolean first = true;
for (DocFile f : DocFile.list(configuration, StandardLocation.SOURCE_PATH, dir)) {
for (DocFile f : DocFile.list(configuration, locn, dir)) {
if (!f.isDirectory()) {
continue;
}
@ -297,7 +335,7 @@ public class Utils {
continue;
}
for (DocFile srcfile: srcdir.list()) {
for (DocFile srcfile: srcdir.list()) {
DocFile destfile = destdir.resolve(srcfile.getName());
if (srcfile.isFile()) {
if (destfile.exists() && !first) {
@ -311,7 +349,7 @@ public class Utils {
} else if (srcfile.isDirectory()) {
if (configuration.copydocfilesubdirs
&& !configuration.shouldExcludeDocFileDir(srcfile.getName())) {
copyDocFiles(dir.resolve(srcfile.getName()));
copyDirectory(locn, dir.resolve(srcfile.getName()));
}
}
}
@ -320,6 +358,21 @@ public class Utils {
}
}
protected Location getLocationForPackage(PackageElement pd) {
return getLocationForModule(configuration.docEnv.getElementUtils().getModuleOf(pd));
}
protected Location getLocationForModule(ModuleElement mdle) {
Location loc = configuration.workArounds.getLocationForModule(mdle);
if (loc != null)
return loc;
JavaFileManager fm = configuration.docEnv.getJavaFileManager();
return fm.hasLocation(StandardLocation.SOURCE_PATH)
? StandardLocation.SOURCE_PATH
: StandardLocation.CLASS_PATH;
}
public boolean isAnnotated(TypeMirror e) {
return !e.getAnnotationMirrors().isEmpty();
}
@ -1568,48 +1621,6 @@ public class Utils {
return secondaryCollator.compare(s1, s2);
}
/**
* @param configuration the configuration for this doclet
* @param locn the location from which to read files
* @param dir the path for the files to be copied
* @throws DocFileIOException if there is a problem copying the files
*/
public void copyDocFiles(Configuration configuration, Location locn, DocPath dir)
throws DocFileIOException {
boolean first = true;
for (DocFile f : DocFile.list(configuration, locn, dir)) {
if (!f.isDirectory()) {
continue;
}
DocFile srcdir = f;
DocFile destdir = DocFile.createFileForOutput(configuration, dir);
if (srcdir.isSameFile(destdir)) {
continue;
}
for (DocFile srcfile: srcdir.list()) {
DocFile destfile = destdir.resolve(srcfile.getName());
if (srcfile.isFile()) {
if (destfile.exists() && !first) {
messages.warning("doclet.Copy_Overwrite_warning",
srcfile.getPath(), destdir.getPath());
} else {
messages.notice("doclet.Copying_File_0_To_Dir_1",
srcfile.getPath(), destdir.getPath());
destfile.copyFile(srcfile);
}
} else if (srcfile.isDirectory()) {
if (configuration.copydocfilesubdirs
&& !configuration.shouldExcludeDocFileDir(srcfile.getName())) {
copyDocFiles(configuration, locn, dir.resolve(srcfile.getName()));
}
}
}
first = false;
}
}
private static class DocCollator {
private final Map<String, CollationKey> keys;
private final Collator instance;

98
langtools/test/jdk/javadoc/doclet/testCopyFiles/TestCopyFiles.java Normal file

@ -0,0 +1,98 @@
/*
* 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.
*
* 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.
*/
/*
* @test
* @bug 8157349
* @summary test copy of doc-files
* @library ../lib
* @modules jdk.javadoc/jdk.javadoc.internal.tool
* @build JavadocTester
* @run main TestCopyFiles
*/
public class TestCopyFiles extends JavadocTester {
public static void main(String... args) throws Exception {
TestCopyFiles tester = new TestCopyFiles();
tester.runTests();
}
@Test
void testDocFilesInModules() {
javadoc("-d", "modules-out",
"--module-source-path", testSrc("modules"),
"--module", "acme.mdle");
checkExit(Exit.OK);
checkOutput("p/doc-files/inpackage.html", true,
"In a named module and named package"
);
}
@Test
void testDocFilesInPackages() {
javadoc("-d", "packages-out",
"-sourcepath", testSrc("packages"),
"p1");
checkExit(Exit.OK);
checkOutput("p1/doc-files/inpackage.html", true,
"A named package in an unnamed module"
);
}
@Test
void testDocFilesInUnnamedPackages() {
javadoc("-d", "unnamed-out",
"-sourcepath", testSrc("unnamed"),
testSrc("unnamed/Foo.java")
);
checkExit(Exit.OK);
checkOutput("doc-files/inpackage.html", true,
"In an unnamed package"
);
}
@Test
void testDocFilesInPackagesSource7() {
javadoc("-d", "packages-out-src7",
"-source", "7",
"-sourcepath", testSrc("packages"),
"p1");
checkExit(Exit.OK);
checkOutput("p1/doc-files/inpackage.html", true,
"A named package in an unnamed module"
);
}
@Test
void testDocFilesInPackagesSource7UsingClassPath() {
javadoc("-d", "packages-out-src7-cp",
"-source", "7",
"-classpath", testSrc("packages"),
"p1");
checkExit(Exit.OK);
checkOutput("p1/doc-files/inpackage.html", true,
"A named package in an unnamed module"
);
}
}

31
langtools/test/jdk/javadoc/doclet/testCopyFiles/modules/acme.mdle/module-info.java Normal file

@ -0,0 +1,31 @@
/*
* 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.
*/
/**
* A test module.
*/
module acme.mdle {
exports p;
}

31
langtools/test/jdk/javadoc/doclet/testCopyFiles/modules/acme.mdle/p/Foo.java Normal file

@ -0,0 +1,31 @@
/*
* 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 p;
/**
* A test class.
*/
public class Foo {}

33
langtools/test/jdk/javadoc/doclet/testCopyFiles/modules/acme.mdle/p/doc-files/inpackage.html Normal file

@ -0,0 +1,33 @@
<!--
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.
-->
<html>
<head>
<title>"Hello World"</title>
</head>
<body>
In a named module and named package
</body>
</html>

34
langtools/test/jdk/javadoc/doclet/testCopyFiles/packages/p1/Foo.java Normal file

@ -0,0 +1,34 @@
/*
* 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.
*/
/**
* A test class.
*/
package p1;
/**
* A test class.
*/
public class Foo {}

33
langtools/test/jdk/javadoc/doclet/testCopyFiles/packages/p1/doc-files/inpackage.html Normal file

@ -0,0 +1,33 @@
<!--
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.
-->
<html>
<head>
<title>"Hello World"</title>
</head>
<body>
A named package in an unnamed module.
</body>
</html>

33
langtools/test/jdk/javadoc/doclet/testCopyFiles/unnamed/Foo.java Normal file

@ -0,0 +1,33 @@
/*
* 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.
*/
/**
* A test class.
*/
/**
* A test class.
*/
public class Foo {}

33
langtools/test/jdk/javadoc/doclet/testCopyFiles/unnamed/doc-files/inpackage.html Normal file

@ -0,0 +1,33 @@
<!--
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.
-->
<html>
<head>
<title>"Hello World"</title>
</head>
<body>
In an unnamed package
</body>
</html>