6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)

Reviewed-by: hannesw

Author: jonathan-gibbons

make/Docs.gmk

@@ -69,8 +69,6 @@ JAVADOC_TAGS := \
     -tag beaninfo:X \
     -tag revised:X \
     -tag since.unbundled:X \
-    -tag spec:X \
-    -tag specdefault:X \
     -tag Note:X \
     -tag ToDo:X \
     -tag 'apiNote:a:API Note:' \
@@ -86,6 +84,7 @@ JAVADOC_TAGS := \
     -tag since \
     -tag serialData \
     -tag factory \
+    -tag spec \
     -tag see \
     -taglet build.tools.taglet.ExtLink \
     -taglet build.tools.taglet.Incubating \

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2022, 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
@@ -218,6 +218,14 @@ enum Kind {
          */
         SNIPPET("snippet"),
 
+        /**
+         * Used for instances of {@link SpecTree}
+         * representing an {@code @spec} tag.
+         *
+         * @since 20
+         */
+        SPEC("spec"),
+
         /**
          * Used for instances of {@link EndElementTree}
          * representing the start of an HTML element.

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2022, 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
@@ -302,6 +302,22 @@ default R visitSnippet(SnippetTree node, P p) {
         return visitOther(node, p);
     }
 
+    /**
+     * Visits a {@code SpecTree} node.
+     *
+     * @implSpec Visits the provided {@code SpecTree} node
+     * by calling {@code visitOther(node, p)}.
+     *
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     *
+     * @since 20
+     */
+    default R visitSpec(SpecTree node, P p) {
+        return visitOther(node, p);
+    }
+
     /**
      * Visits a {@code StartElementTree} node.
      * @param node the node being visited

src/jdk.compiler/share/classes/com/sun/source/doctree/SpecTree.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2019, 2022, 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.source.doctree;
+
+import java.util.List;
+
+/**
+ * A tree node for an {@code @spec} block tag.
+ *
+ * <pre>
+ *    &#064;spec url title
+ * </pre>
+ *
+ * @since 20
+ */
+public interface SpecTree extends BlockTagTree {
+    /**
+     * {@return the URL}
+     */
+    TextTree getURL();
+
+    /**
+     * {@return the title}
+     */
+    List<? extends DocTree> getTitle();
+}

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java

@@ -59,6 +59,7 @@
 import com.sun.source.doctree.SerialTree;
 import com.sun.source.doctree.SinceTree;
 import com.sun.source.doctree.SnippetTree;
+import com.sun.source.doctree.SpecTree;
 import com.sun.source.doctree.StartElementTree;
 import com.sun.source.doctree.SummaryTree;
 import com.sun.source.doctree.SystemPropertyTree;
@@ -336,6 +337,15 @@ default ReturnTree newReturnTree(boolean isInline, List<? extends DocTree> descr
      */
     SnippetTree newSnippetTree(List<? extends DocTree> attributes, TextTree text);
 
+    /**
+     * Creates a new {@code SpecTree} object, to represent an {@code @spec} tag.
+     * @param url    the url
+     * @param title  the title
+     * @return a {@code SpecTree} object
+     * @since 20
+     */
+    SpecTree newSpecTree(TextTree url, List<? extends DocTree> title);
+
     /**
      * Creates a new {@code StartElementTree} object, to represent the start of an HTML element.
      * @param name the name of the HTML element

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java

@@ -515,6 +515,23 @@ public R visitSnippet(SnippetTree node, P p) {
         return r;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @implSpec This implementation scans the children in left to right order.
+     *
+     * @param node {@inheritDoc}
+     * @param p    {@inheritDoc}
+     * @return the result of scanning
+     * @since 20
+     */
+    @Override
+    public R visitSpec(SpecTree node, P p) {
+        R r = scan(node.getURL(), p);
+        r = scanAndReduce(node.getTitle(), p, r);
+        return r;
+    }
+
     /**
      * {@inheritDoc}
      *

src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2022, 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
@@ -463,6 +463,23 @@ public R visitSnippet(SnippetTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @implSpec This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p    {@inheritDoc}
+     *
+     * @return  the result of {@code defaultAction}
+     *
+     * @since 20
+     */
+    @Override
+    public R visitSpec(SpecTree node, P p) {
+        return defaultAction(node, p);
+    }
+
     /**
      * {@inheritDoc}
      *

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java

@@ -1551,6 +1551,24 @@ private List<DCTree> tagAttrs() {
                 }
             },
 
+            // @spec url label
+            new TagParser(TagParser.Kind.BLOCK, DCTree.Kind.SPEC) {
+                @Override
+                public DCTree parse(int pos) throws ParseException {
+                    skipWhitespace();
+                    DCText url = inlineWord();
+                    if (url == null || url.isBlank()) {
+                        throw new ParseException("dc.no.url");
+                    }
+                    skipWhitespace();
+                    List<DCTree> title = blockContent();
+                    if (title.isEmpty() || DCTree.isBlank(title)) {
+                        throw new ParseException("dc.no.title");
+                    }
+                    return m.at(pos).newSpecTree(url, title);
+                }
+            },
+
             // {@summary summary-text}
             new TagParser(TagParser.Kind.INLINE, DCTree.Kind.SUMMARY) {
                 @Override

src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties

@@ -3322,6 +3322,12 @@ compiler.err.dc.no.content=\
 compiler.err.dc.no.tag.name=\
     no tag name after '@'
 
+compiler.err.dc.no.url=\
+    no URL
+
+compiler.err.dc.no.title=\
+    no title
+
 compiler.err.dc.gt.expected=\
     ''>'' expected
 

src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java

@@ -42,7 +42,6 @@
 import com.sun.tools.javac.util.DefinedBy;
 import com.sun.tools.javac.util.DefinedBy.Api;
 import com.sun.tools.javac.util.JCDiagnostic;
-import com.sun.tools.javac.util.Position;
 
 import static com.sun.tools.javac.util.Position.NOPOS;
 
@@ -225,6 +224,14 @@ public int getEndPosition() {
         return NOPOS;
     }
 
+    public boolean isBlank() {
+        return false;
+    }
+
+    public static boolean isBlank(List<? extends DCTree> list) {
+        return list.stream().allMatch(DCTree::isBlank);
+    }
+
     /**
      * Convert a tree to a pretty-printed string.
      */
@@ -1080,6 +1087,41 @@ public TextTree getBody() {
         }
     }
 
+    public static class DCSpec extends DCBlockTag implements SpecTree {
+        public final DCText uri;
+        public final List<DCTree> title;
+
+        DCSpec(DCText uri, List<DCTree> title) {
+            this.uri = uri;
+            this.title = title;
+        }
+
+        @Override
+        public String getTagName() {
+            return "spec";
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public Kind getKind() {
+            return Kind.SPEC;
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitSpec(this, d);
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public TextTree getURL() {
+            return uri;
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public List<? extends DocTree> getTitle() {
+            return title;
+        }
+    }
+
     public static class DCStartElement extends DCEndPosTree<DCStartElement> implements StartElementTree {
         public final Name name;
         public final List<DCTree> attrs;
@@ -1170,6 +1212,11 @@ public static class DCText extends DCTree implements TextTree {
             this.text = text;
         }
 
+        @Override
+        public boolean isBlank() {
+            return text.isBlank();
+        }
+
         @Override @DefinedBy(Api.COMPILER_TREE)
         public Kind getKind() {
             return Kind.TEXT;

src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocPretty.java

@@ -504,6 +504,20 @@ public Void visitSnippet(SnippetTree node, Void p) {
         return null;
     }
 
+    @Override @DefinedBy(Api.COMPILER_TREE)
+    public Void visitSpec(SpecTree node, Void p) {
+        try {
+            printTagName(node);
+            print(" ");
+            print(node.getURL());
+            print(" ");
+            print(node.getTitle());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
     @Override @DefinedBy(Api.COMPILER_TREE)
     public Void visitStartElement(StartElementTree node, Void p) {
         try {

src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java

@@ -76,6 +76,7 @@
 import com.sun.tools.javac.tree.DCTree.DCSerialField;
 import com.sun.tools.javac.tree.DCTree.DCSince;
 import com.sun.tools.javac.tree.DCTree.DCSnippet;
+import com.sun.tools.javac.tree.DCTree.DCSpec;
 import com.sun.tools.javac.tree.DCTree.DCStartElement;
 import com.sun.tools.javac.tree.DCTree.DCSummary;
 import com.sun.tools.javac.tree.DCTree.DCSystemProperty;
@@ -89,9 +90,7 @@
 import com.sun.tools.javac.util.Context;
 import com.sun.tools.javac.util.DefinedBy;
 import com.sun.tools.javac.util.DefinedBy.Api;
-import com.sun.tools.javac.util.DiagnosticSource;
 import com.sun.tools.javac.util.JCDiagnostic;
-import com.sun.tools.javac.util.JCDiagnostic.DiagnosticPosition;
 import com.sun.tools.javac.util.ListBuffer;
 import com.sun.tools.javac.util.Pair;
 import com.sun.tools.javac.util.Position;
@@ -124,7 +123,7 @@ public static DocTreeMaker instance(Context context) {
 
     /** The position at which subsequent trees will be created.
      */
-    public int pos = Position.NOPOS;
+    public int pos;
 
     private final JavacTrees trees;
 
@@ -238,9 +237,8 @@ public boolean isDeprecated() {
             }
         };
         Pair<List<DCTree>, List<DCTree>> pair = splitBody(fullBody);
-        DCDocComment tree = new DCDocComment(c, fBody, pair.fst, pair.snd, cast(tags),
+        return new DCDocComment(c, fBody, pair.fst, pair.snd, cast(tags),
                                              cast(preamble), cast(postamble));
-        return tree;
     }
 
     @Override @DefinedBy(Api.COMPILER_TREE)
@@ -421,6 +419,13 @@ public DCSnippet newSnippetTree(List<? extends DocTree> attributes, TextTree tex
         return tree;
     }
 
+    @Override @DefinedBy(Api.COMPILER_TREE)
+    public DCSpec newSpecTree(TextTree url, List<? extends DocTree> title) {
+        DCSpec tree = new DCSpec((DCText) url, cast(title));
+        tree.pos = pos;
+        return tree;
+    }
+
     @Override @DefinedBy(Api.COMPILER_TREE)
     public DCStartElement newStartElementTree(Name name, List<? extends DocTree> attrs, boolean selfClosing) {
         DCStartElement tree = new DCStartElement(name, cast(attrs), selfClosing);