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

jonathan-gibbons · 2020-10-22T02:40:44Z

This introduces support for a new @spec tag that can be used as either an inline tag or as a block tag. It is used to identify references to external specifications, in such a way that the references can be collected together on a new summary page, called "Other Specifications", available from either the static INDEX page or the interactive search box.

As an inline tag, the format is {@spec url label}, which is roughly translated to <a href="url">label</a> in the generated docs.

As a block tag, the format is simply

@spec url label

which is handled in a manner analogous to

@see <a href="url">label</a>

The tag is notable for being the first standard/supported tag that can be used as either an inline or block tag. (We have had support for bimodal non-standard/custom tags for a while, such as {@jls} and {@jvms}.) To support bimodal standard tags, some changes to DocCommentParser are incorporated here.

This change is only the support for the new tag; it does not include any changes to API docs to use the new tag.

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Testing

	Linux aarch64	Linux arm	Linux ppc64le	Linux s390x	Linux x64	Linux x86	Windows x64	macOS x64
Build	✔️ (1/1 passed)	✔️ (1/1 passed)	✔️ (1/1 passed)	✔️ (1/1 passed)	✔️ (6/6 passed)	✔️ (2/2 passed)	✔️ (2/2 passed)	✔️ (2/2 passed)
Test (tier1)					✔️ (9/9 passed)	✔️ (9/9 passed)	✔️ (9/9 passed)	✔️ (9/9 passed)

Integration blocker

⚠️ The change requires a CSR request to be approved.

Issues

JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)
JDK-8226279: javadoc should support a new @SPEC tag

Reviewers

Erik Joelsson (@erikj79 - Reviewer) ⚠️ Review applies to c777637
Hannes Wallnöfer (@hns - Reviewer) ⚠️ Review applies to c777637

Download

$ git fetch https://git.openjdk.java.net/jdk pull/790/head:pull/790
$ git checkout pull/790

…uments referenced from javadocs (OEM spec)

bridgekeeper · 2020-10-22T02:41:01Z

👋 Welcome back jjg! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2020-10-22T02:43:11Z

@jonathan-gibbons The following labels will be automatically applied to this pull request:

build
compiler
javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

jonathan-gibbons · 2020-10-23T01:00:37Z

/issue add JDK-8226279

openjdk · 2020-10-23T01:02:04Z

@jonathan-gibbons
Adding additional issue to issue list: 8226279: javadoc should support a new @spec tag.

jonathan-gibbons · 2020-10-23T15:43:14Z

/csr

openjdk · 2020-10-23T15:44:06Z

@jonathan-gibbons has indicated that a compatibility and specification (CSR) request is needed for this pull request.
@jonathan-gibbons please create a CSR request and add link to it in JDK-6251738. This pull request cannot be integrated until the CSR request is approved.

mlbridge · 2020-10-23T15:50:48Z

Webrevs

erikj79

Build changes look good.

hns

It's very instructive to see a new tag introduced from scratch with all the accompanying infrastructure and tests. The changes looks good to me, but I need to stress than I'm not an expert on some of the affected areas such as the jdk.compiler parts.

openjdk · 2020-11-04T15:53:42Z

@jonathan-gibbons this pull request can not be integrated into master due to one or more merge conflicts. To resolve these merge conflicts and update this pull request you can run the following commands in the local repository for your personal fork:

git checkout new-spec-tag
git fetch https://git.openjdk.java.net/jdk master
git merge FETCH_HEAD
# resolve conflicts and follow the instructions given by git merge
git commit -m "Merge master"
git push

pavelrappo · 2020-11-05T13:13:12Z

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

+    /**
+     * Creates a new {@code SpecTree} object, to represent a {@code @spec} tag.
+     *
+     * @param inline whether this is instance is an inline tag


Should be:
* @param inline whether this instance is an inline tag

pavelrappo

Thanks for incorporating my previous offline feedback.
Since Hannes and Erik seem to have looked at everything else, I looked mostly at changes in src/jdk.compiler/share/classes/com/sun/source/**, which are good!
There should be a corresponding but separate change to "Documentation Comment Specification for the Standard Doclet".
Can we use this new @since tag to refer to the spec at com/sun/tools/javac/parser/DocCommentParser.java:1116?
Should we specify in com.sun.source.doctree.SpecTree that both url and label parts are mandatory?
DCSpec extends DCEndPosTree, sigh... Although that is not a public API, this design suggests we could improve that abstraction sometime later.

pavelrappo · 2020-11-05T13:24:34Z

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

        }

        DCTree.Kind getTreeKind() {
            return treeKind;
        }

-        abstract DCTree parse(int pos) throws ParseException;
+        DCTree parse(int pos, Kind kind) throws ParseException {
+            if (kind != this.kind && this.kind != Kind.EITHER) {


This condition looks right, but shouldn't we add another one to guard against accidental passing of kind == EITHER?

pavelrappo · 2020-11-05T14:13:29Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java

@@ -300,6 +301,7 @@ public static String encodeURL(String url) {

    /**
     * Creates an HTML {@code A} element.
+     * The {@code ref} argument will be URL-encoded for use as the attribute value.
     *
     * @param ref the value for the {@code href} attribute}


Since you are here, could you please remove that trailing }?

pavelrappo · 2020-11-05T14:14:31Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java

+     * and will <i>not</i> be additionally URL-encoded, but will be
+     * {@link URI#toASCIIString() converted} to ASCII for use as the attribute value.
+     *
+     * @param ref the value for the {@code href} attribute}


One more, perhaps copy-pasted, trailing }.

pavelrappo · 2020-11-05T14:28:33Z

test/langtools/tools/javac/diags/examples/NoLabel.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 2020 Oracle and/or its affiliates. All rights reserved.


Should be:
Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.

pavelrappo · 2020-11-05T15:44:20Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java

@@ -257,6 +263,13 @@ public Content seeTagOutput(Element holder, List<? extends SeeTree> seeTags) {
                HtmlTree.DD(body));
    }

+    String textOf(List<? extends DocTree> trees) {


I wonder if this method should work recursively rather than shallowly. Consider the following example:

@spec http://example.com Some code: {@code text}

I reckon we'll end up with only Some code: .

pavelrappo · 2020-11-05T15:51:23Z

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

+    public boolean isBlank() {
+        return false;
+    }
+
+    public static boolean isBlank(List<? extends DCTree> list) {
+        return list.stream().allMatch(DCTree::isBlank);
+    }
+


Adding these two methods here might be overkill.

pavelrappo · 2020-11-05T16:16:15Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java

@@ -733,7 +734,7 @@ private void showTaglets(PrintStream out) {
        taglets.addAll(allTaglets.values());

        for (Taglet t : taglets) {
-            String name = t.isInlineTag() ? "{@" + t.getName() + "}" : "@" + t.getName();
+            String name = t.isBlockTag() ? "@" + t.getName() : "{@" + t.getName() + "}";


Out of curiosity, why did you flip that?

jonathan-gibbons · 2020-12-16T18:26:34Z

Closing pull request, until we better decide the contents of the spec page

JDK-6251738: Want a top-level summary page that itemizes all spec doc…

3181d9f

…uments referenced from javadocs (OEM spec)

openjdk bot added javadoc javadoc-dev@openjdk.org build build-dev@openjdk.org compiler compiler-dev@openjdk.org labels Oct 22, 2020

jonathan-gibbons added 5 commits October 22, 2020 08:26

temporarily allow existing legacy usage @spec JPMS @spec jsr-51

9923acb

fix trailing whitespace in test

34e61db

Merge remote-tracking branch 'upstream/master' into new-spec-tag

ba6bbf9

remove support to workaround legacy @SPEC tag

d66ebfe

fix tests

0f27f9c

fix TestSpecTag.testEncodedURI

c777637

openjdk bot added the csr Pull request needs approved CSR before integration label Oct 23, 2020

jonathan-gibbons marked this pull request as ready for review October 23, 2020 15:46

openjdk bot added the rfr Pull request is ready for review label Oct 23, 2020

erikj79 approved these changes Oct 23, 2020

View reviewed changes

hns approved these changes Nov 4, 2020

View reviewed changes

openjdk bot added the merge-conflict Pull request has merge conflict with target branch label Nov 4, 2020

jonathan-gibbons added 4 commits November 4, 2020 10:29

update Docs.gmk to stop disabling spec tag

177afbc

allow rich content in createAnchorAndSearchIndex

0e2bf88

Merge with master

7ca701e

Fix merge issues; review feedback

ed5512d

openjdk bot removed the merge-conflict Pull request has merge conflict with target branch label Nov 4, 2020

pavelrappo reviewed Nov 5, 2020

View reviewed changes

pavelrappo suggested changes Nov 5, 2020

View reviewed changes

Merge master

69595e0

jonathan-gibbons closed this Dec 16, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

jonathan-gibbons commented Oct 22, 2020 •

edited by openjdk bot

Loading

bridgekeeper bot commented Oct 22, 2020

openjdk bot commented Oct 22, 2020

jonathan-gibbons commented Oct 23, 2020

openjdk bot commented Oct 23, 2020

jonathan-gibbons commented Oct 23, 2020

openjdk bot commented Oct 23, 2020

mlbridge bot commented Oct 23, 2020 •

edited

Loading

erikj79 left a comment

hns left a comment

openjdk bot commented Nov 4, 2020

pavelrappo Nov 5, 2020

pavelrappo left a comment

pavelrappo Nov 5, 2020

pavelrappo Nov 5, 2020

pavelrappo Nov 5, 2020

pavelrappo Nov 5, 2020

pavelrappo Nov 5, 2020

pavelrappo Nov 5, 2020

pavelrappo Nov 5, 2020

jonathan-gibbons commented Dec 16, 2020

		@@ -0,0 +1,32 @@
		/*
		* Copyright (c) 2012, 2020 Oracle and/or its affiliates. All rights reserved.

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

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

Conversation

jonathan-gibbons commented Oct 22, 2020 • edited by openjdk bot Loading

Progress

Testing

Integration blocker

Issues

Reviewers

Download

bridgekeeper bot commented Oct 22, 2020

openjdk bot commented Oct 22, 2020

jonathan-gibbons commented Oct 23, 2020

openjdk bot commented Oct 23, 2020

jonathan-gibbons commented Oct 23, 2020

openjdk bot commented Oct 23, 2020

mlbridge bot commented Oct 23, 2020 • edited Loading

Webrevs

erikj79 left a comment

Choose a reason for hiding this comment

hns left a comment

Choose a reason for hiding this comment

openjdk bot commented Nov 4, 2020

Choose a reason for hiding this comment

pavelrappo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathan-gibbons commented Dec 16, 2020

jonathan-gibbons commented Oct 22, 2020 •

edited by openjdk bot

Loading

mlbridge bot commented Oct 23, 2020 •

edited

Loading