You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by pa...@apache.org on 2026/04/21 06:13:37 UTC
(groovy) 26/34: GROOVY-11945: recognise @apiNote, @implSpec, @implNote block tags
This is an automated email from the ASF dual-hosted git repository.
paulk-asert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git
commit 91646945a1081434d4f11d1830b9f5e4616a7775
Author: Paul King <pa...@asert.com.au>
AuthorDate: Tue Apr 21 06:42:30 2026 +1000
GROOVY-11945: recognise @apiNote, @implSpec, @implNote block tags
---
.../groovy/tools/groovydoc/TagRenderer.java | 8 +++++
.../groovy/tools/groovydoc/GroovyDocToolTest.java | 34 +++++++++++++++++++
.../testfiles/ClassWithImplNoteTags.groovy | 38 ++++++++++++++++++++++
3 files changed, 80 insertions(+)
diff --git a/subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java b/subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java
index d4f9ea023d..ad9083f171 100644
--- a/subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java
+++ b/subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java
@@ -90,6 +90,14 @@ final class TagRenderer {
/** Block-tag names that get merged under a single display heading. */
static final Map<String, String> COLLATED_TAGS = new LinkedHashMap<>();
static {
+ // GROOVY-11945: three "note" tags standardised by Javadoc's stdlib
+ // doclet since JEP 172. Recognised so the display heading is right
+ // (not the raw lowercase tag name) and so the bodies are collated
+ // with the rest of the block tags rather than emitted inline at
+ // source position.
+ COLLATED_TAGS.put("apiNote", "API Note");
+ COLLATED_TAGS.put("implSpec", "Implementation Requirements");
+ COLLATED_TAGS.put("implNote", "Implementation Note");
COLLATED_TAGS.put("see", "See Also");
COLLATED_TAGS.put("param", "Parameters");
COLLATED_TAGS.put("throw", "Throws");
diff --git a/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java
index 17f17296bb..9098e34e21 100644
--- a/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java
+++ b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java
@@ -533,6 +533,40 @@ public class GroovyDocToolTest extends GroovyTestCase {
snippet.contains("@link"));
}
+ // GROOVY-11945: @apiNote / @implSpec / @implNote render with their
+ // Javadoc-standard display headings (not the raw lowercase tag names),
+ // and their bodies get collated into the tags section alongside
+ // @param / @return.
+ public void testImplNoteTagsRenderWithProperHeadings() throws Exception {
+ String base = "org/codehaus/groovy/tools/groovydoc/testfiles";
+ htmlTool.add(List.of(base + "/ClassWithImplNoteTags.groovy"));
+ MockOutputTool output = new MockOutputTool();
+ htmlTool.renderToOutput(output, MOCK_DIR);
+
+ String page = output.getText(MOCK_DIR + "/" + base + "/ClassWithImplNoteTags.html");
+ assertNotNull(page);
+ assertTrue("API Note heading expected in:\n" + page,
+ page.contains("<B>API Note:</B>"));
+ assertTrue("Implementation Requirements heading expected in:\n" + page,
+ page.contains("<B>Implementation Requirements:</B>"));
+ assertTrue("Implementation Note heading expected in:\n" + page,
+ page.contains("<B>Implementation Note:</B>"));
+ // Bodies reach the rendered page.
+ assertTrue("apiNote body expected:\n" + page,
+ page.contains("null-check the result"));
+ assertTrue("implSpec body expected:\n" + page,
+ page.contains("non-negative contract"));
+ assertTrue("implNote body expected:\n" + page,
+ page.contains("uses a sieve for efficiency"));
+ // Raw lowercase tag name should NOT appear as a heading.
+ assertFalse("Raw 'implNote:' should not leak as a heading:\n" + page,
+ page.contains("<B>implNote:</B>"));
+ assertFalse("Raw 'implSpec:' should not leak as a heading:\n" + page,
+ page.contains("<B>implSpec:</B>"));
+ assertFalse("Raw 'apiNote:' should not leak as a heading:\n" + page,
+ page.contains("<B>apiNote:</B>"));
+ }
+
// GROOVY-11938 stage 3 region support: a directive with region="name"
// activates at its line and applies until the matching // @end marker.
public void testSnippetMarkupRegionScoping() throws Exception {
diff --git a/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/ClassWithImplNoteTags.groovy b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/ClassWithImplNoteTags.groovy
new file mode 100644
index 0000000000..0ebdb9495f
--- /dev/null
+++ b/subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/ClassWithImplNoteTags.groovy
@@ -0,0 +1,38 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.codehaus.groovy.tools.groovydoc.testfiles
+
+/**
+ * GROOVY-11945 fixture: a method documented with the three Javadoc "note"
+ * tags standardised since JEP 172, alongside ordinary block tags.
+ */
+class ClassWithImplNoteTags {
+ /**
+ * Compute something.
+ *
+ * @apiNote Callers should null-check the result before use.
+ * @implSpec Overriders must preserve the non-negative contract.
+ * @implNote This implementation uses a sieve for efficiency.
+ * @param n the input value
+ * @return a non-negative integer
+ */
+ int compute(int n) {
+ return Math.abs(n)
+ }
+}