# HG changeset patch # User chegar # Date 1381843031 -3600 # Node ID 46feacb99698c7ad2f08ed9ec454555f64dfcff9 # Parent 86e57f576e65faf1c5469a599155df984fb4a4b0# Parent 09a41467357071086a60196137ad5d7614cab1d7 Merge diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/javadoc/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/com/sun/javadoc/package-info.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,148 @@ +/* + * Copyright (c) 1998, 2013, 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. + */ + +/** +The Doclet API (also called the Javadoc API) provides a mechanism +for clients to inspect the source-level structure of programs and +libraries, including javadoc comments embedded in the source. +This is useful for documentation, program checking, automatic +code generation and many other tools. +

+ +Doclets are invoked by javadoc and use this API to write out +program information to files. For example, the standard doclet is called +by default and writes out documentation to HTML files. +

+ +The invocation is defined by the abstract {@link com.sun.javadoc.Doclet} class +-- the entry point is the {@link com.sun.javadoc.Doclet#start(RootDoc) start} method: +

+    public static boolean start(RootDoc root)
+
+The {@link com.sun.javadoc.RootDoc} instance holds the root of the program structure +information. From this root all other program structure +information can be extracted. +

+ + +

Terminology

+ + +When calling javadoc, you pass in package names and source file names -- +these are called the specified packages and classes. +You also pass in Javadoc options; the access control Javadoc options +(-public, -protected, -package, +and -private) filter program elements, producing a +result set, called the included set, or "documented" set. +(The unfiltered set is also available through +{@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.) +

+ + +Throughout this API, the term class is normally a +shorthand for "class or interface", as in: {@link com.sun.javadoc.ClassDoc}, +{@link com.sun.javadoc.PackageDoc#allClasses() allClasses()}, and +{@link com.sun.javadoc.PackageDoc#findClass(String) findClass(String)}. +In only a couple of other places, it means "class, as opposed to interface", +as in: {@link com.sun.javadoc.Doc#isClass()}. +In the second sense, this API calls out four kinds of classes: +{@linkplain com.sun.javadoc.Doc#isOrdinaryClass() ordinary classes}, +{@linkplain com.sun.javadoc.Doc#isEnum() enums}, +{@linkplain com.sun.javadoc.Doc#isError() errors} and +{@linkplain com.sun.javadoc.Doc#isException() exceptions}. +Throughout the API, the detailed description of each program element +describes explicitly which meaning is being used. +

+ + +A qualified class or interface name is one that has its package +name prepended to it, such as java.lang.String. A non-qualified +name has no package name, such as String. +

+ + +

Example

+ +The following is an example doclet that +displays information in the @param tags of the processed +classes: +
+import com.sun.javadoc.*;
+
+public class ListParams extends Doclet {
+
+    public static boolean start(RootDoc root) {
+        ClassDoc[] classes = root.classes();
+        for (int i = 0; i < classes.length; ++i) {
+            ClassDoc cd = classes[i];
+            printMembers(cd.constructors());
+            printMembers(cd.methods());
+        }
+        return true;
+    }
+
+    static void printMembers(ExecutableMemberDoc[] mems) {
+        for (int i = 0; i < mems.length; ++i) {
+            ParamTag[] params = mems[i].paramTags();
+            System.out.println(mems[i].qualifiedName());
+            for (int j = 0; j < params.length; ++j) {
+                System.out.println("   " + params[j].parameterName()
+                    + " - " + params[j].parameterComment());
+            }
+        }
+    }
+}
+
+Interfaces and methods from the Javadoc API are marked in +red. +{@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies +the invocation interface for doclets, +{@link com.sun.javadoc.Doclet Doclet} holds class or interface information, +{@link com.sun.javadoc.ExecutableMemberDoc} is a +superinterface of {@link com.sun.javadoc.MethodDoc} and +{@link com.sun.javadoc.ConstructorDoc}, +and {@link com.sun.javadoc.ParamTag} holds information +from "@param" tags. +

+This doclet when invoked with a command line like: +

+    javadoc -doclet ListParams -sourcepath <source-location> java.util
+
+producing output like: +
+    ...
+    java.util.ArrayList.add
+       index - index at which the specified element is to be inserted.
+       element - element to be inserted.
+    java.util.ArrayList.remove
+       index - the index of the element to removed.
+    ...
+
+
+@see com.sun.javadoc.Doclet +@see com.sun.javadoc.RootDoc +*/ +@jdk.Exported +package com.sun.javadoc; diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/javadoc/package.html --- a/src/share/classes/com/sun/javadoc/package.html Fri Oct 11 19:05:18 2013 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,152 +0,0 @@ - - -Doclet API Package - - - - -The Doclet API (also called the Javadoc API) provides a mechanism -for clients to inspect the source-level structure of programs and -libraries, including javadoc comments embedded in the source. -This is useful for documentation, program checking, automatic -code generation and many other tools. -

- -Doclets are invoked by javadoc and use this API to write out -program information to files. For example, the standard doclet is called -by default and writes out documentation to HTML files. -

- -The invocation is defined by the abstract {@link com.sun.javadoc.Doclet} class --- the entry point is the {@link com.sun.javadoc.Doclet#start(RootDoc) start} method: -

-    public static boolean start(RootDoc root)
-
-The {@link com.sun.javadoc.RootDoc} instance holds the root of the program structure -information. From this root all other program structure -information can be extracted. -

- - -

Terminology

- - -When calling javadoc, you pass in package names and source file names -- -these are called the specified packages and classes. -You also pass in Javadoc options; the access control Javadoc options -(-public, -protected, -package, -and -private) filter program elements, producing a -result set, called the included set, or "documented" set. -(The unfiltered set is also available through -{@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.) -

- - -Throughout this API, the term class is normally a -shorthand for "class or interface", as in: {@link com.sun.javadoc.ClassDoc}, -{@link com.sun.javadoc.PackageDoc#allClasses() allClasses()}, and -{@link com.sun.javadoc.PackageDoc#findClass(String) findClass(String)}. -In only a couple of other places, it means "class, as opposed to interface", -as in: {@link com.sun.javadoc.Doc#isClass()}. -In the second sense, this API calls out four kinds of classes: -{@linkplain com.sun.javadoc.Doc#isOrdinaryClass() ordinary classes}, -{@linkplain com.sun.javadoc.Doc#isEnum() enums}, -{@linkplain com.sun.javadoc.Doc#isError() errors} and -{@linkplain com.sun.javadoc.Doc#isException() exceptions}. -Throughout the API, the detailed description of each program element -describes explicitly which meaning is being used. -

- - -A qualified class or interface name is one that has its package -name prepended to it, such as java.lang.String. A non-qualified -name has no package name, such as String. -

- - -

Example

- -The following is an example doclet that -displays information in the @param tags of the processed -classes: -
-import com.sun.javadoc.*;
-
-public class ListParams extends Doclet {
-
-    public static boolean start(RootDoc root) {
-        ClassDoc[] classes = root.classes();
-        for (int i = 0; i < classes.length; ++i) {
-            ClassDoc cd = classes[i];
-            printMembers(cd.constructors());
-            printMembers(cd.methods());
-        }
-        return true;
-    }
-
-    static void printMembers(ExecutableMemberDoc[] mems) {
-        for (int i = 0; i < mems.length; ++i) {
-            ParamTag[] params = mems[i].paramTags();
-            System.out.println(mems[i].qualifiedName());
-            for (int j = 0; j < params.length; ++j) {
-                System.out.println("   " + params[j].parameterName()
-                    + " - " + params[j].parameterComment());
-            }
-        }
-    }        
-}
-
-Interfaces and methods from the Javadoc API are marked in -red. -{@link com.sun.javadoc.Doclet Doclet} is an abstract class that specifies -the invocation interface for doclets, -{@link com.sun.javadoc.Doclet Doclet} holds class or interface information, -{@link com.sun.javadoc.ExecutableMemberDoc} is a -superinterface of {@link com.sun.javadoc.MethodDoc} and -{@link com.sun.javadoc.ConstructorDoc}, -and {@link com.sun.javadoc.ParamTag} holds information -from "@param" tags. -

-This doclet when invoked with a command line like: -

-    javadoc -doclet ListParams -sourcepath <source-location> java.util
-
-producing output like: -
-    ...
-    java.util.ArrayList.add
-       index - index at which the specified element is to be inserted.
-       element - element to be inserted.
-    java.util.ArrayList.remove
-       index - the index of the element to removed.
-    ...
-
-
-@see com.sun.javadoc.Doclet -@see com.sun.javadoc.RootDoc - - diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/classfile/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/com/sun/tools/classfile/package-info.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,37 @@ +/* + * Copyright (c) 2007, 2013, 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 minimalist library to read and write class files into objects closely + based on the corresponding definitions in + The Java™ Virtual Machine Specification (JVMS). + +

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. +*/ +@jdk.Exported(false) +package com.sun.tools.classfile; diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/classfile/package.html --- a/src/share/classes/com/sun/tools/classfile/package.html Fri Oct 11 19:05:18 2013 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - - - - A minimalist library to read and write class files into objects closely - based on the corresponding definitions in - The Java™ Virtual Machine Specification (JVMS). - - diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/doclets/formats/html/markup/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/com/sun/tools/doclets/formats/html/markup/package-info.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,35 @@ +/* + * Copyright (c) 2007, 2013, 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. + */ + +/** + This package contains classes that write HTML markup tags. + +

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. + */ +@jdk.Exported(false) +package com.sun.tools.doclets.formats.html.markup; diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/doclets/formats/html/markup/package.html --- a/src/share/classes/com/sun/tools/doclets/formats/html/markup/package.html Fri Oct 11 19:05:18 2013 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,32 +0,0 @@ - - - - -com.sun.tools.doclets.formats.html.markup package - - This package contains classes that write HTML markup tags. - - diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/doclets/formats/html/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/com/sun/tools/doclets/formats/html/package-info.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,40 @@ +/* + * Copyright (c) 2003, 2013, 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. + */ + +/** + This is the default doclet provided with JDK that produces Javadoc's + default HTML-formatted API output. For more documentation + on this doclet, please refer to the link below. + + @see + http://www.java.sun.com/javadoc/standard-doclet.html + +

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. +*/ +@jdk.Exported(false) +package com.sun.tools.doclets.formats.html; diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/doclets/formats/html/package.html --- a/src/share/classes/com/sun/tools/doclets/formats/html/package.html Fri Oct 11 19:05:18 2013 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ - - - - -com.sun.tools.doclets.formats.html package - - - This is the default doclet provided with JDK that produces Javadoc's - default HTML-formatted API output. For more documentation - on this doclet, please refer to the link below. - - @see - http://www.java.sun.com/javadoc/standard-doclet.html - - diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/package-info.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,41 @@ +/* + * Copyright (c) 2003, 2013, 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. + */ + +/** + This doclet-independent package has a set of classes and + interfaces that are the building blocks for doclets. They + define the basic structure of doclets and make doclet + writing much easier because they provide the content generation + code to be shared among different doclets. Builders only provide + the structure and content of API documentation. + They will not provide any style markup. + +

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. +*/ +@jdk.Exported(false) +package com.sun.tools.doclets.internal.toolkit.builders; diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/package.html --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/package.html Fri Oct 11 19:05:18 2013 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,43 +0,0 @@ - - - - -com.sun.tools.doclets.internal.toolkit.builders package - - - This doclet-independent package has a set of classes and - interfaces that are the building blocks for doclets. They - define the basic structure of doclets and make doclet - writing much easier because they provide the content generation - code to be shared among different doclets. Builders only provide - the structure and content of API documentation. - They will not provide any style markup. -

- This code is not part of an API. - It is implementation that is subject to change. - Do not use it as an API. - - diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/doclets/internal/toolkit/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/package-info.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,57 @@ +/* + * Copyright (c) 2003, 2013, 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. + */ + +/** + Contains the base classes that make up a doclet. Doclets that reuse + the functionality provided by the toolkit should have the following + characteristics: +

+ +

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. +*/ +@jdk.Exported(false) +package com.sun.tools.doclets.internal.toolkit; diff -r 86e57f576e65 -r 46feacb99698 src/share/classes/com/sun/tools/doclets/internal/toolkit/package.html --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/package.html Fri Oct 11 19:05:18 2013 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,55 +0,0 @@ - - - - -com.sun.tools.doclets.internal.toolkit package - - - - Contains the base classes that make up a doclet. Doclets that reuse - the functionality provided by the toolkit should have the following - characteristics: -

+ diff -r 86e57f576e65 -r 46feacb99698 test/tools/doclint/HtmlAttrsTest.java --- a/test/tools/doclint/HtmlAttrsTest.java Fri Oct 11 19:05:18 2013 +0100 +++ b/test/tools/doclint/HtmlAttrsTest.java Tue Oct 15 14:17:11 2013 +0100 @@ -10,7 +10,7 @@ /** */ public class HtmlAttrsTest { /** - *

+ *

text

*/ public void unknown() { } diff -r 86e57f576e65 -r 46feacb99698 test/tools/doclint/HtmlAttrsTest.out --- a/test/tools/doclint/HtmlAttrsTest.out Fri Oct 11 19:05:18 2013 +0100 +++ b/test/tools/doclint/HtmlAttrsTest.out Tue Oct 15 14:17:11 2013 +0100 @@ -1,5 +1,5 @@ HtmlAttrsTest.java:13: error: unknown attribute: xyz - *

+ *

text

^ HtmlAttrsTest.java:18: warning: attribute obsolete: name * alt diff -r 86e57f576e65 -r 46feacb99698 test/tools/doclint/tidy/BadEnd.out --- a/test/tools/doclint/tidy/BadEnd.out Fri Oct 11 19:05:18 2013 +0100 +++ b/test/tools/doclint/tidy/BadEnd.out Tue Oct 15 14:17:11 2013 +0100 @@ -1,6 +1,9 @@ BadEnd.java:14: warning: nested tag not allowed: * text ^ +BadEnd.java:14: warning: empty tag + * text + ^ BadEnd.java:14: error: element not closed: code * text ^ @@ -14,4 +17,4 @@ * text ^ 4 errors -1 warning +2 warnings diff -r 86e57f576e65 -r 46feacb99698 test/tools/doclint/tidy/TrimmingEmptyTag.java --- a/test/tools/doclint/tidy/TrimmingEmptyTag.java Fri Oct 11 19:05:18 2013 +0100 +++ b/test/tools/doclint/tidy/TrimmingEmptyTag.java Tue Oct 15 14:17:11 2013 +0100 @@ -1,6 +1,6 @@ /* * @test /nodynamiccopyright/ - * @bug 8004832 + * @bug 8004832 8026368 * @summary Add new doclint package * @library .. * @build DocLintTester @@ -26,4 +26,9 @@ *
    *
    */ -public class TrimmingEmptyTag { } +public class TrimmingEmptyTag { + /**

    */ + public void implicitParaEnd_endOfComment() { } + /**

    • text
    */ + public void implicitParaEnd_nextBlockTag() { } +} diff -r 86e57f576e65 -r 46feacb99698 test/tools/doclint/tidy/TrimmingEmptyTag.out --- a/test/tools/doclint/tidy/TrimmingEmptyTag.out Fri Oct 11 19:05:18 2013 +0100 +++ b/test/tools/doclint/tidy/TrimmingEmptyTag.out Tue Oct 15 14:17:11 2013 +0100 @@ -43,4 +43,10 @@ TrimmingEmptyTag.java:26: warning: empty
      tag *
        ^ -15 warnings +TrimmingEmptyTag.java:30: warning: empty

        tag + /**

        */ + ^ +TrimmingEmptyTag.java:32: warning: empty

        tag + /**

        • text
        */ + ^ +17 warnings diff -r 86e57f576e65 -r 46feacb99698 test/tools/javac/annotations/typeAnnotations/failures/CantAnnotateStaticClass.out --- a/test/tools/javac/annotations/typeAnnotations/failures/CantAnnotateStaticClass.out Fri Oct 11 19:05:18 2013 +0100 +++ b/test/tools/javac/annotations/typeAnnotations/failures/CantAnnotateStaticClass.out Tue Oct 15 14:17:11 2013 +0100 @@ -1,10 +1,10 @@ CantAnnotateStaticClass.java:22:20: compiler.err.cant.annotate.static.class CantAnnotateStaticClass.java:23:13: compiler.err.cant.annotate.static.class CantAnnotateStaticClass.java:24:29: compiler.err.cant.annotate.static.class -CantAnnotateStaticClass.java:26:29: compiler.err.cant.annotate.static.class CantAnnotateStaticClass.java:29:26: compiler.err.cant.annotate.static.class CantAnnotateStaticClass.java:30:9: compiler.err.cant.annotate.static.class CantAnnotateStaticClass.java:31:35: compiler.err.cant.annotate.static.class +CantAnnotateStaticClass.java:26:29: compiler.err.cant.annotate.static.class - compiler.note.unchecked.filename: CantAnnotateStaticClass.java - compiler.note.unchecked.recompile -7 errors +7 errors \ No newline at end of file diff -r 86e57f576e65 -r 46feacb99698 test/tools/javac/lambda/LocalVariableTable.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/tools/javac/lambda/LocalVariableTable.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,206 @@ +/* + * Copyright (c) 2013, 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 8025998 + * @summary Missing LV table in lambda bodies + * @compile -g LocalVariableTable.java + * @run main LocalVariableTable + */ + +import java.lang.annotation.*; +import java.util.*; +import com.sun.tools.classfile.*; + +/* + * The test checks that a LocalVariableTable attribute is generated for the + * method bodies representing lambda expressions, and checks that the expected + * set of entries is found in the attribute. + * + * Since the bug was about missing entries in the LVT, not malformed entries, + * the test is not intended to be a detailed test of the contents of each + * LocalVariableTable entry: it is assumed that if a entry is present, it + * will have the correct contents. + * + * The test looks for test cases represented by nested classes whose + * name begins with "Lambda". Each such class contains a lambda expression + * that will mapped into a lambda method, and because the test is compiled + * with -g, these methods should have a LocalVariableTable. The set of + * expected names in the LVT is provided in an annotation on the class for + * the test case. + */ +public class LocalVariableTable { + public static void main(String... args) throws Exception { + new LocalVariableTable().run(); + } + + void run() throws Exception { + // the declared classes are returned in an unspecified order, + // so for neatness, sort them by name before processing them + Class[] classes = getClass().getDeclaredClasses(); + Arrays.sort(classes, (c1, c2) -> c1.getName().compareTo(c2.getName())); + + for (Class c : classes) { + if (c.getSimpleName().startsWith("Lambda")) + check(c); + } + if (errors > 0) + throw new Exception(errors + " errors found"); + } + + /** Check an individual test case. */ + void check(Class c) throws Exception { + System.err.println("Checking " + c.getSimpleName()); + + Expect expect = c.getAnnotation(Expect.class); + if (expect == null) { + error("@Expect not found for class " + c.getSimpleName()); + return; + } + + ClassFile cf = ClassFile.read(getClass().getResource(c.getName() + ".class").openStream()); + Method m = getLambdaMethod(cf); + if (m == null) { + error("lambda method not found"); + return; + } + + Code_attribute code = (Code_attribute) m.attributes.get(Attribute.Code); + if (code == null) { + error("Code attribute not found"); + return; + } + + LocalVariableTable_attribute lvt = + (LocalVariableTable_attribute) code.attributes.get(Attribute.LocalVariableTable); + if (lvt == null) { + error("LocalVariableTable attribute not found"); + return; + } + + Set foundNames = new LinkedHashSet<>(); + for (LocalVariableTable_attribute.Entry e: lvt.local_variable_table) { + foundNames.add(cf.constant_pool.getUTF8Value(e.name_index)); + } + + Set expectNames = new LinkedHashSet<>(Arrays.asList(expect.value())); + if (!foundNames.equals(expectNames)) { + Set foundOnly = new LinkedHashSet<>(foundNames); + foundOnly.removeAll(expectNames); + for (String s: foundOnly) + error("Unexpected name found: " + s); + Set expectOnly = new LinkedHashSet<>(expectNames); + expectOnly.removeAll(foundNames); + for (String s: expectOnly) + error("Expected name not found: " + s); + } + } + + /** Get a method whose name begins "lambda$...". */ + Method getLambdaMethod(ClassFile cf) throws ConstantPoolException { + for (Method m: cf.methods) { + if (m.getName(cf.constant_pool).startsWith("lambda$")) + return m; + } + return null; + } + + /** Report an error. */ + void error(String msg) { + System.err.println("Error: " + msg); + errors++; + } + + int errors; + + /** + * Annotation used to provide the set of names expected in the LVT attribute. + */ + @Retention(RetentionPolicy.RUNTIME) + @interface Expect { + String[] value(); + } + + /** Functional interface with nullary method. */ + interface Run0 { + public void run(); + } + + /** Functional interface with 1-ary method. */ + interface Run1 { + public void run(int a0); + } + + /** Functional interface with 2-ary method. */ + interface Run2 { + public void run(int a0, int a1); + } + + /* + * ---------- Test cases --------------------------------------------------- + */ + + @Expect({ "x" }) + static class Lambda_Args0_Local1 { + Run0 r = () -> { int x = 0; }; + } + + @Expect({ "x", "this" }) + static class Lambda_Args0_Local1_this { + int v; + Run0 r = () -> { int x = v; }; + } + + @Expect({ "a" }) + static class Lambda_Args1_Local0 { + Run1 r = (a) -> { }; + } + + @Expect({ "a", "x" }) + static class Lambda_Args1_Local1 { + Run1 r = (a) -> { int x = a; }; + } + + @Expect({ "a", "x" }) + static class Lambda_Args1_Local1_Captured1 { + void m() { + int v = 0; + Run1 r = (a) -> { int x = a + v; }; + } + } + + @Expect({ "a1", "a2", "x1", "x2", "this" }) + static class Lambda_Args2_Local2_Captured2_this { + int v; + void m() { + int v1 = 0; + int v2 = 0; + Run2 r = (a1, a2) -> { + int x1 = a1 + v1 + v; + int x2 = a2 + v2 + v; + }; + } + } +} + diff -r 86e57f576e65 -r 46feacb99698 test/tools/javac/processing/errors/StopOnInapplicableAnnotations/GenerateFunctionalInterface.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/tools/javac/processing/errors/StopOnInapplicableAnnotations/GenerateFunctionalInterface.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,38 @@ +/* + * Copyright (c) 2013, 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 8014016 + * @summary Ensure that an annotation processor can generate a super-interface + * which will make the current interface functional + * @build GenerateSuperInterfaceProcessor + * @compile -processor GenerateSuperInterfaceProcessor GenerateFunctionalInterface.java + */ + +import java.lang.FunctionalInterface; + +@FunctionalInterface +@Generate(fileName="SuperInterface.java", content="interface SuperInterface { public void run(); }") +interface GenerateFunctionalInterface extends SuperInterface { +} diff -r 86e57f576e65 -r 46feacb99698 test/tools/javac/processing/errors/StopOnInapplicableAnnotations/GenerateSuperInterfaceProcessor.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/tools/javac/processing/errors/StopOnInapplicableAnnotations/GenerateSuperInterfaceProcessor.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,60 @@ +/* + * Copyright (c) 2013, 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. + */ + +import com.sun.tools.javac.util.Assert; +import java.io.IOException; +import java.io.OutputStream; +import java.util.Set; +import javax.annotation.processing.AbstractProcessor; +import javax.annotation.processing.RoundEnvironment; +import javax.annotation.processing.SupportedAnnotationTypes; +import javax.lang.model.element.Element; +import javax.lang.model.element.TypeElement; + +@SupportedAnnotationTypes("*") +public class GenerateSuperInterfaceProcessor extends AbstractProcessor { + + @Override + public boolean process(Set annotations, RoundEnvironment roundEnv) { + for (Element el : roundEnv.getElementsAnnotatedWith(Generate.class)) { + Generate g = el.getAnnotation(Generate.class); + + Assert.checkNonNull(g); + + try (OutputStream out = + processingEnv.getFiler().createSourceFile(g.fileName()).openOutputStream()) { + out.write(g.content().getBytes()); + } catch (IOException ex) { + throw new IllegalStateException(ex); + } + } + + return false; + } + +} + +@interface Generate { + String fileName(); + String content(); +} \ No newline at end of file diff -r 86e57f576e65 -r 46feacb99698 test/tools/javac/processing/errors/StopOnInapplicableAnnotations/Processor.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/tools/javac/processing/errors/StopOnInapplicableAnnotations/Processor.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,170 @@ +/* + * Copyright (c) 2013, 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. + */ + +import com.sun.source.tree.AnnotationTree; +import com.sun.source.tree.CompilationUnitTree; +import com.sun.source.util.JavacTask; +import com.sun.source.util.TreeScanner; +import com.sun.source.util.Trees; +import com.sun.tools.javac.api.JavacTool; +import com.sun.tools.javac.file.JavacFileManager; +import com.sun.tools.javac.util.Assert; +import java.io.File; +import java.io.IOException; +import java.net.URI; +import java.net.URISyntaxException; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.Comparator; +import java.util.List; +import java.util.Set; +import javax.annotation.processing.AbstractProcessor; +import javax.annotation.processing.RoundEnvironment; +import javax.annotation.processing.SupportedAnnotationTypes; +import javax.lang.model.element.TypeElement; +import javax.tools.Diagnostic; +import javax.tools.DiagnosticListener; +import javax.tools.FileObject; +import javax.tools.ForwardingJavaFileManager; +import javax.tools.JavaFileManager; +import javax.tools.JavaFileObject; +import javax.tools.SimpleJavaFileObject; + +@SupportedAnnotationTypes("*") +public class Processor extends AbstractProcessor { + + @Override + public boolean process(Set annotations, RoundEnvironment roundEnv) { + throw new IllegalStateException("Should not be invoked."); + } + + public static void main(String... args) throws IOException, URISyntaxException { + if (args.length != 1) throw new IllegalStateException("Must provide class name!"); + String testContent = null; + List sourcePath = new ArrayList<>(); + for (String sourcePaths : System.getProperty("test.src.path").split(":")) { + sourcePath.add(new File(sourcePaths)); + } + JavacFileManager fm = JavacTool.create().getStandardFileManager(null, null, null); + for (File sp : sourcePath) { + File inp = new File(sp, args[0]); + + if (inp.canRead()) { + testContent = fm.getRegularFile(inp).getCharContent(true).toString(); + } + } + if (testContent == null) throw new IllegalStateException(); + DiagnosticListener devNull = new DiagnosticListener() { + @Override public void report(Diagnostic diagnostic) { } + }; + JavaFileObject testFile = new TestFO(new URI("mem://" + args[0]), testContent); + JavacTask task = JavacTool.create().getTask(null, + new TestFM(fm), + devNull, + Arrays.asList("-Xjcov"), + null, + Arrays.asList(testFile)); + final Trees trees = Trees.instance(task); + final CompilationUnitTree cut = task.parse().iterator().next(); + task.analyze(); + + final List annotations = new ArrayList<>(); + + new TreeScanner() { + @Override + public Void visitAnnotation(AnnotationTree node, Void p) { + int endPos = (int) trees.getSourcePositions().getEndPosition(cut, node); + + Assert.check(endPos >= 0); + + annotations.add(new int[] {(int) trees.getSourcePositions().getStartPosition(cut, node), endPos}); + return super.visitAnnotation(node, p); + } + }.scan(cut.getTypeDecls().get(0), null); + + Collections.sort(annotations, new Comparator() { + @Override public int compare(int[] o1, int[] o2) { + return o2[0] - o1[0]; + } + }); + + for (final int[] annotation : annotations) { + StringBuilder updatedContent = new StringBuilder(); + int last = testContent.length(); + + for (int[] toRemove : annotations) { + if (toRemove == annotation) continue; + updatedContent.insert(0, testContent.substring(toRemove[1], last)); + last = toRemove[0]; + } + + updatedContent.insert(0, testContent.substring(0, last)); + + JavaFileObject updatedFile = new TestFO(new URI("mem://" + args[0]), updatedContent.toString()); + JavacTask testTask = JavacTool.create().getTask(null, + new TestFM(fm), + devNull, + Arrays.asList("-processor", "Processor"), + null, + Arrays.asList(updatedFile)); + + try { + testTask.analyze(); + } catch (Throwable e) { + System.out.println("error while processing:"); + System.out.println(updatedContent); + throw e; + } + } + } + + private static final class TestFO extends SimpleJavaFileObject { + private final String content; + public TestFO(URI uri, String content) { + super(uri, Kind.SOURCE); + this.content = content; + } + + @Override public CharSequence getCharContent(boolean ignoreEncodingErrors) throws IOException { + return content; + } + + @Override public boolean isNameCompatible(String simpleName, Kind kind) { + return true; + } + } + + private static final class TestFM extends ForwardingJavaFileManager { + + public TestFM(JavaFileManager fileManager) { + super(fileManager); + } + + @Override + public boolean isSameFile(FileObject a, FileObject b) { + return a.equals(b); + } + + } +} \ No newline at end of file diff -r 86e57f576e65 -r 46feacb99698 test/tools/javac/processing/errors/StopOnInapplicableAnnotations/Source.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/tools/javac/processing/errors/StopOnInapplicableAnnotations/Source.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,59 @@ +/* + * Copyright (c) 2013, 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 8014016 + * @summary Verify that annotation processors do not get invalid annotations + * @build Processor + * @run main Processor Source.java + */ + +import java.lang.annotation.ElementType; +import java.lang.annotation.Target; + +@OnMethod +@OnField +class Class<@OnType @OnMethod @OnField T extends @OnType @OnMethod @OnField CharSequence & @OnType @OnMethod @OnField Runnable> extends @OnType @OnMethod @OnField Object { + + @OnType + @OnTypeUse + @OnField + private void testMethod(@OnType @OnField @OnMethod int i) { } + + @OnType + @OnMethod + private java.lang.@OnType @OnMethod @OnField String testField; +} + +@Target(ElementType.TYPE) +@interface OnType {} + +@Target(ElementType.METHOD) +@interface OnMethod {} + +@Target(ElementType.TYPE_USE) +@interface OnTypeUse {} + +@Target(ElementType.FIELD) +@interface OnField {} diff -r 86e57f576e65 -r 46feacb99698 test/tools/javadoc/8025693/Test.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/tools/javadoc/8025693/Test.java Tue Oct 15 14:17:11 2013 +0100 @@ -0,0 +1,91 @@ +/* + * Copyright (c) 2013, 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 8025693 + * @summary javadoc should ignore methods found in classes on classpath + */ + +import java.io.*; + +public class Test { + public static void main(String[] args) throws Exception { + new Test().run(); + } + + final File baseFile = new File("src/Base.java"); + final String baseText = + "package p;\n" + + "public class Base { static { } }\n"; + + final File srcFile = new File("src/C.java"); + final String srcText = + "package p;\n" + + "/** comment */\n" + + "public abstract class C extends Base { }\n"; + + void run() throws Exception { + File classesDir = new File("classes"); + classesDir.mkdirs(); + writeFile(baseFile, baseText); + String[] javacArgs = { + "-d", classesDir.getPath(), + baseFile.getPath() + }; + com.sun.tools.javac.Main.compile(javacArgs); + + writeFile(srcFile, srcText); + String[] args = { + "-d", "api", + "-classpath", classesDir.getPath(), + "-package", "p", + srcFile.getPath() + }; + + ByteArrayOutputStream baos = new ByteArrayOutputStream(); + PrintStream ps = new PrintStream(baos); + PrintStream prev = System.err; + System.setErr(ps); + try { + int rc = com.sun.tools.javadoc.Main.execute(args); + } finally { + System.err.flush(); + System.setErr(prev); + } + String out = baos.toString(); + System.out.println(out); + + String errorMessage = "java.lang.IllegalArgumentException: "; + if (out.contains(errorMessage)) + throw new Exception("error message found: " + errorMessage); + } + + void writeFile(File file, String body) throws IOException { + file.getParentFile().mkdirs(); + try (FileWriter out = new FileWriter(file)) { + out.write(body); + } + } +} +