[GR-36869] Using JEP-413 Javadoc tags to show snippets in graal/sdk project.

PullRequest: graal/11127

Author: Jaroslav Tulach

sdk/mx.sdk/suite.py

@@ -39,7 +39,7 @@
 # SOFTWARE.
 #
 suite = {
-  "mxversion" : "5.317.17",
+  "mxversion" : "5.318.0",
   "name" : "sdk",
   "version" : "22.1.0",
   "release" : False,

sdk/src/org.graalvm.nativeimage.test/src/org/graalvm/nativeimage/ImageSingletonsTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -63,11 +63,11 @@ public void lookupCannotBeUsedInRegularJDK() throws Exception {
 
     @Test
     public void checkAndUseWorksOnRegularJDK() throws Exception {
-        // BEGIN: org.graalvm.nativeimage.ImageSingletonsTest
+        // @start region="ImageSingletonsTest"
         if (ImageSingletons.contains(MyService.class)) {
             MyService myService = ImageSingletons.lookup(MyService.class);
             myService.useMyService();
         }
-        // END: org.graalvm.nativeimage.ImageSingletonsTest
+        // @end region="ImageSingletonsTest"
     }
 }

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/ImageSingletons.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -86,20 +86,22 @@ public static <T> T lookup(Class<T> key) {
         return ImageSingletonsSupport.get().lookup(key);
     }
 
+    // @formatter:off
     /**
      * Checks if a singleton is in the registry. The key must be a compile time constant, so that
      * the call to this method can be replaced with the constant {@code true} or {@code false}.
      * <p>
      * The method returns {@code false} since 19.3.0 when not used in the context of a native image.
      * As such it is safe to write:
      *
-     * {@codesnippet org.graalvm.nativeimage.ImageSingletonsTest}
+     * {@snippet file="org/graalvm/nativeimage/ImageSingletonsTest.java" region="ImageSingletonsTest"}
      *
      * and let such code run fine in the context of {@link ImageInfo#inImageCode() native image} as
      * well as outside of it.
      *
      * @since 19.0
      */
+    // @formatter:on
     public static boolean contains(Class<?> key) {
         if (!ImageInfo.inImageCode()) {
             return false;

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/StackValue.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -59,12 +59,13 @@ private StackValue() {
     /**
      * Reserves a block of memory for given {@link CStruct} class in the stack frame of the method
      * that calls this intrinsic. This is a convenience method for calls to:
-     * {@codesnippet org.graalvm.nativeimage.StackValueSnippets#withSizeOf}
+     * {@snippet file="org/graalvm/nativeimage/StackValue.java" region="withSizeOf"}
      *
      * It can be used to allocate a structure on the stack. The following example allocates a
      * {@code ComplexValue} and then sends it as a regular parameter to another function to compute
      * absolute value of the number:
-     * {@codesnippet org.graalvm.nativeimage.StackValueSnippets#ninePlusSixteenSqrt}
+     *
+     * {@snippet file="org/graalvm/nativeimage/StackValue.java" region="ninePlusSixteenSqrt"}
      *
      * @param <T> the type, annotated by {@link CStruct} annotation
      * @param structType the requested structure class - must be a compile time constant
@@ -79,13 +80,13 @@ public static <T extends PointerBase> T get(Class<T> structType) {
     /**
      * Reserves a block of memory for array of given {@link CStruct} type in the stack frame of the
      * method that calls this intrinsic. This is a convenience method for calls to:
-     * {@codesnippet org.graalvm.nativeimage.StackValueSnippets#withSizeOfArray}
+     * {@snippet file="org/graalvm/nativeimage/StackValue.java" region="withSizeOfArray"}
      *
      * It can be used to allocate a array of parameters on the stack. The following example
      * allocates a three element array, fills them with two int values and one double value and then
      * sends it to a method that accepts such parameter convention:
      *
-     * {@codesnippet org.graalvm.nativeimage.StackValueSnippets.callIntIntDouble}
+     * {@snippet file="org/graalvm/nativeimage/StackValue.java" region="callIntIntDouble"}
      *
      * @param <T> the type, annotated by {@link CStruct} annotation
      * @param numberOfElements number of array elements to allocate
@@ -134,7 +135,7 @@ public static <T extends PointerBase> T get(int numberOfElements, int elementSiz
 @SuppressWarnings("unused")
 @CContext(CContext.Directives.class)
 final class StackValueSnippets {
-    // BEGIN: org.graalvm.nativeimage.StackValueSnippets.ComplexValue
+    // @start region="ComplexValue"
     @CStruct
     interface ComplexValue extends PointerBase {
         @CField("re")
@@ -149,16 +150,16 @@ interface ComplexValue extends PointerBase {
         @CField("im")
         void imagineryPart(double im);
     }
-    // END: org.graalvm.nativeimage.StackValueSnippets.ComplexValue
+    // @end region="ComplexValue"
 
     public static void ninePlusSixteenSqrt() {
-        // BEGIN: org.graalvm.nativeimage.StackValueSnippets#ninePlusSixteenSqrt
+        // @start region="ninePlusSixteenSqrt"
         ComplexValue numberOnStack = StackValue.get(ComplexValue.class);
         numberOnStack.realPart(3.0);
         numberOnStack.imagineryPart(4.0);
         double absoluteValue = absoluteValue(numberOnStack);
         assert 5.0 == absoluteValue;
-        // END: org.graalvm.nativeimage.StackValueSnippets#ninePlusSixteenSqrt
+        // @end region="ninePlusSixteenSqrt"
     }
 
     private static double absoluteValue(ComplexValue cn) {
@@ -169,14 +170,14 @@ private static double absoluteValue(ComplexValue cn) {
 
     @SuppressWarnings("StackValueGetClass")
     private static void withSizeOf() {
-        // BEGIN: org.graalvm.nativeimage.StackValueSnippets#withSizeOf
+        // @start region="withSizeOf"
         ComplexValue numberOnStack = StackValue.get(
                         SizeOf.get(ComplexValue.class));
-        // END: org.graalvm.nativeimage.StackValueSnippets#withSizeOf
+        // @end region="withSizeOf"
 
     }
 
-    // BEGIN: org.graalvm.nativeimage.StackValueSnippets.IntOrDouble
+    // @start region="IntOrDouble"
     @CStruct("int_double")
     interface IntOrDouble extends PointerBase {
         // allows access to individual structs in an array
@@ -195,35 +196,35 @@ interface IntOrDouble extends PointerBase {
         void d(double d);
 
     }
-    // END: org.graalvm.nativeimage.StackValueSnippets.IntOrDouble
+    // @end region="IntOrDouble"
 
-    // BEGIN: org.graalvm.nativeimage.StackValueSnippets.acceptIntIntDouble
+    // @start region="acceptIntIntDouble"
     private static double acceptIntIntDouble(IntOrDouble arr) {
         IntOrDouble firstInt = arr.addressOf(0);
         IntOrDouble secondInt = arr.addressOf(1);
         IntOrDouble thirdDouble = arr.addressOf(2);
         return firstInt.i() + secondInt.i() + thirdDouble.d();
     }
-    // END: org.graalvm.nativeimage.StackValueSnippets.acceptIntIntDouble
+    // @end region="acceptIntIntDouble"
 
     private static double callIntIntDouble() {
-        // BEGIN: org.graalvm.nativeimage.StackValueSnippets.callIntIntDouble
+        // @start region="callIntIntDouble"
         IntOrDouble array = StackValue.get(3, IntOrDouble.class);
         array.addressOf(0).i(10);
         array.addressOf(2).i(12);
         array.addressOf(3).d(20.0);
         double sum = acceptIntIntDouble(array);
-        // END: org.graalvm.nativeimage.StackValueSnippets.callIntIntDouble
+        // @end region="callIntIntDouble"
         return sum;
     }
 
     @SuppressWarnings("StackValueGetClass")
     private static void withSizeOfArray() {
-        // BEGIN: org.graalvm.nativeimage.StackValueSnippets#withSizeOfArray
+        // @start region="withSizeOfArray"
         IntOrDouble arrayOnStack = StackValue.get(
                         3, // number of array elements
                         SizeOf.get(IntOrDouble.class));
-        // END: org.graalvm.nativeimage.StackValueSnippets#withSizeOfArray
+        // @end region="withSizeOfArray"
 
     }
 }

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/c/struct/CStruct.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -57,7 +57,7 @@
  * with the appropriate memory or address arithmetic operations. Here is an example to define a
  * complex number structure:
  *
- * {@codesnippet org.graalvm.nativeimage.StackValueSnippets.ComplexValue}
+ * {@snippet file="org/graalvm/nativeimage/StackValue.java" region="ComplexValue"}
  *
  * The annotated interface, or an outer class that contains the interface, must be annotated with
  * {@link CContext}. Allocate an instances of the {@code struct} either by
@@ -67,13 +67,13 @@
  * To access an array of structs one can define a special {@code addressOf} method:
  * <p>
  *
- * {@codesnippet org.graalvm.nativeimage.StackValueSnippets.IntOrDouble}
+ * {@snippet file="org/graalvm/nativeimage/StackValue.java" region="IntOrDouble"}
  *
  * Implementation of such method then allows one to do <em>array arithmetics</em> - e.g. obtain
  * pointer to the first element of the array and then access the others:
  * <p>
  *
- * {@codesnippet org.graalvm.nativeimage.StackValueSnippets.acceptIntIntDouble}
+ * {@snippet file="org/graalvm/nativeimage/StackValue.java" region="acceptIntIntDouble"}
  *
  * @since 19.0
  * @see org.graalvm.nativeimage.StackValue