diff --git a/doc-comment-spec.md b/doc-comment-spec.md --- a/doc-comment-spec.md +++ b/doc-comment-spec.md @@ -1613,6 +1613,15 @@ Introduced in JDK 1.0. +### `info` + +* `@info` _text_ + +Provides an "Info" block to highlight API guidance, security considerations, +performance notes, replacement pointers and other important details. Introduced in JDK 25. + +Introduced in JDK 25. + @@ -1651,6 +1660,7 @@ | [`uses`](#uses) | ✓ | | | | | | | | [`value`](#value) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | [`version`](#version) | ✓ | ✓ | ✓ | | | | ✓ | +| [`info`](#info) | ✓ | ✓ | ✓ | &check | &check | &check | ✓ | _Notes:_ =================================================================== diff --git a/open/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java b/open/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java --- a/open/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java (revision 8545e1357142db2e008970095a3f74f8121dbcf2) +++ b/open/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java (revision dbfd4f6bb42fa531248b4c102813002243f79ae4) @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2011, 2025, 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 @@ -264,6 +264,16 @@ */ SUMMARY("summary"), + + /** + * Used for instances of {@link InfoTree} + * representing an {@code @info} tag. + * + * @since 25 + */ + INFO("info"), + + /** * Used for instances of {@link TextTree} * representing some plain documentation text. =================================================================== diff --git a/open/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java b/open/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java --- a/open/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java (revision 8545e1357142db2e008970095a3f74f8121dbcf2) +++ b/open/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java (revision dbfd4f6bb42fa531248b4c102813002243f79ae4) @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2011, 2025, 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 @@ -372,6 +372,21 @@ default R visitSummary(SummaryTree node, P p) { return visitOther(node, p); } + + /** + * Visits a {@code InfoTree} node. + * + * @implSpec Visits the provided {@code InfoTree} node + * by calling {@code visitOther(node, p)}. + * + * @param node the node being visited + * @param p a parameter value + * @return a result value + * @since 25 + */ + default R visitInfo(InfoTree node, P p) { + return visitOther(node, p); + } /** * Visits a {@code SystemPropertyTree} node. =================================================================== diff --git a/open/src/jdk.compiler/share/classes/com/sun/source/doctree/InfoTree.java b/open/src/jdk.compiler/share/classes/com/sun/source/doctree/InfoTree.java new file mode 100644 --- /dev/null (revision dbfd4f6bb42fa531248b4c102813002243f79ae4) +++ b/open/src/jdk.compiler/share/classes/com/sun/source/doctree/InfoTree.java (revision dbfd4f6bb42fa531248b4c102813002243f79ae4) @@ -0,0 +1,7 @@ +package com.sun.source.doctree; + +import java.util.List; + +public interface InfoTree extends BlockTagTree{ + List getReference(); +} =================================================================== diff --git a/open/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java b/open/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java --- a/open/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java (revision 8545e1357142db2e008970095a3f74f8121dbcf2) +++ b/open/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java (revision dbfd4f6bb42fa531248b4c102813002243f79ae4) @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2011, 2025, 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 @@ -74,6 +74,7 @@ import com.sun.source.doctree.UsesTree; import com.sun.source.doctree.ValueTree; import com.sun.source.doctree.VersionTree; +import com.sun.source.doctree.InfoTree; /** * Factory for creating {@code DocTree} nodes. @@ -387,6 +388,14 @@ */ SnippetTree newSnippetTree(List attributes, TextTree text); + + /** + * Creates a new {@code InfoTree} object, to represent a {@code {@info}} tag. + * @param attributes the attributes of the tag + * @since 25 + */ + InfoTree newInfoTree(List attributes); + /** * Creates a new {@code SpecTree} object, to represent an {@code @spec} tag. * @param url the url =================================================================== diff --git a/open/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java b/open/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java --- a/open/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java (revision 8545e1357142db2e008970095a3f74f8121dbcf2) +++ b/open/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java (revision dbfd4f6bb42fa531248b4c102813002243f79ae4) @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2011, 2025, 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 @@ -548,6 +548,23 @@ r = scanAndReduce(node.getBody(), p, r); 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 25 + */ + @Override + public R visitInfo(InfoTree node, P p) { + R r = scan(node.getReference(), p); + r = scanAndReduce(node.getReference(), p, r); + return r; + } /** * {@inheritDoc} =================================================================== diff --git a/open/src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java b/open/src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java --- a/open/src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java (revision 8545e1357142db2e008970095a3f74f8121dbcf2) +++ b/open/src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java (revision dbfd4f6bb42fa531248b4c102813002243f79ae4) @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2025, 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 @@ -540,6 +540,20 @@ public R visitSummary(SummaryTree 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 25 + */ + @Override + public R visitInfo(InfoTree node, P p) { + return defaultAction(node, p); + } /** * {@inheritDoc}