From 66b0a6cb8961eb96105bfde4d29144f0a90e7a75 Mon Sep 17 00:00:00 2001
From: Lukas Jungmann <lukas.jungmann@oracle.com>
Date: Thu, 26 Oct 2023 16:12:05 +0200
Subject: [PATCH] improve code samples in javadoc

Signed-off-by: Lukas Jungmann <lukas.jungmann@oracle.com>
---
 .../jakarta/annotation/PostConstruct.java     |  8 +-
 .../java/jakarta/annotation/PreDestroy.java   |  6 +-
 .../annotation/sql/DataSourceDefinition.java  | 93 +++++++++----------
 3 files changed, 53 insertions(+), 54 deletions(-)

diff --git a/api/src/main/java/jakarta/annotation/PostConstruct.java b/api/src/main/java/jakarta/annotation/PostConstruct.java
index ea1784a..e8cef7f 100644
--- a/api/src/main/java/jakarta/annotation/PostConstruct.java
+++ b/api/src/main/java/jakarta/annotation/PostConstruct.java
@@ -30,7 +30,7 @@
  * not request any resources to be injected. Only one 
  * method in a given class can be annotated with this annotation. 
  * The method on which the {@code PostConstruct} annotation is
- * applied must fulfill all of the following criteria:
+ * applied must fulfill all the following criteria:
  * <ul>
  * <li>The method must not have any parameters except in the case of 
  * interceptors in which case it takes an {@code InvocationContext}
@@ -38,9 +38,9 @@
  * <li>The method defined on an interceptor class or superclass of an
  * interceptor class must have one of the following signatures:
  * <p>
- * void &#060;METHOD&#062;(InvocationContext)
+ * {@code void <METHOD>(InvocationContext)}
  * <p>
- * Object &#060;METHOD&#062;(InvocationContext) throws Exception
+ * {@code Object <METHOD>(InvocationContext) throws Exception}
  * <p>
  * <i>Note: A PostConstruct interceptor method must not throw application 
  * exceptions, but it may be declared to throw checked exceptions including 
@@ -52,7 +52,7 @@
  * <li>The method defined on a non-interceptor class must have the 
  * following signature:
  * <p>
- * void &#060;METHOD&#062;()
+ * {@code void <METHOD>()}
  * </li>
  * <li>The method on which the {@code PostConstruct} annotation
  * is applied may be public, protected, package private or private.</li>
diff --git a/api/src/main/java/jakarta/annotation/PreDestroy.java b/api/src/main/java/jakarta/annotation/PreDestroy.java
index 6685c11..b4ebdd1 100644
--- a/api/src/main/java/jakarta/annotation/PreDestroy.java
+++ b/api/src/main/java/jakarta/annotation/PreDestroy.java
@@ -37,9 +37,9 @@
  * <li>The method defined on an interceptor class or superclass of an
  * interceptor class must have one of the following signatures:
  * <p>
- * void &#060;METHOD&#062;(InvocationContext)
+ * {@code void <METHOD>(InvocationContext)}
  * <p>
- * Object &#060;METHOD&#062;(InvocationContext) throws Exception
+ * {@code Object <METHOD>(InvocationContext) throws Exception}
  * <p>
  * <i>Note: A PreDestroy interceptor method must not throw application
  * exceptions, but it may be declared to throw checked exceptions including
@@ -51,7 +51,7 @@
  * <li>The method defined on a non-interceptor class must have the
  * following signature:
  * <p>
- * void &#060;METHOD&#062;()
+ * {@code void <METHOD>()}
  * </li>
  * <li>The method on which PreDestroy is applied may be public, protected,
  * package private or private.</li>
diff --git a/api/src/main/java/jakarta/annotation/sql/DataSourceDefinition.java b/api/src/main/java/jakarta/annotation/sql/DataSourceDefinition.java
index 14c3528..fc8c021 100644
--- a/api/src/main/java/jakarta/annotation/sql/DataSourceDefinition.java
+++ b/api/src/main/java/jakarta/annotation/sql/DataSourceDefinition.java
@@ -46,16 +46,16 @@
  * the properties annotation element, the precedence order is undefined
  * and implementation specific:
  * <p>
- * <pre>
- *   &#064;DataSourceDefinition(name="java:global/MyApp/MyDataSource",
- *      className="org.apache.derby.jdbc.ClientDataSource",
- *      url="jdbc:derby://localhost:1527/myDB;user=bill",
- *      user="lance",
- *      password="secret",
- *      databaseName="testDB",
- *      serverName="luckydog"
- *   )// DO NOT DO THIS!!!
- * </pre>
+ * {@snippet :
+ * @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
+ *     className="org.apache.derby.jdbc.ClientDataSource",
+ *     url="jdbc:derby://localhost:1527/myDB;user=bill",
+ *     user="lance",
+ *     password="secret",
+ *     databaseName="testDB",
+ *     serverName="luckydog"
+ * )// DO NOT DO THIS!!!
+ * }
  * <p>
  * In the above example, the {@code databaseName}, {@code user}
  * and {@code serverName} properties were specified as part of the
@@ -67,16 +67,16 @@
  * annotation element, the annotation element value takes precedence.
  * For example:
  * <p>
- * <pre>
- *   &#064;DataSourceDefinition(name="java:global/MyApp/MyDataSource",
- *      className="org.apache.derby.jdbc.ClientDataSource",
- *      user="lance",
- *      password="secret",
- *      databaseName="testDB",
- *      serverName="luckydog",
- *       properties= {"databaseName=myDB", "databaseProp=doThis"}
+ * {@snippet :
+ * @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
+ *     className="org.apache.derby.jdbc.ClientDataSource",
+ *     user="lance",
+ *     password="secret",
+ *     databaseName="testDB",
+ *     serverName="luckydog",
+ *     properties= {"databaseName=myDB", "databaseProp=doThis"}
  *   )// DO NOT DO THIS!!!
- * </pre>
+ * }
  * <p>
  * This would result in the following values being used when configuring
  * the DataSource:
@@ -104,38 +104,37 @@
  * <p>
  * Examples:
  * <br>
- *  <pre>
- *   &#064;DataSourceDefinition(name="java:global/MyApp/MyDataSource",
- *      className="com.foobar.MyDataSource",
- *      portNumber=6689,
- *      serverName="myserver.com",
- *      user="lance",
- *      password="secret"
- *   )
- *
- * </pre>
+ * {@snippet :
+ * @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
+ *     className="com.foobar.MyDataSource",
+ *     portNumber=6689,
+ *     serverName="myserver.com",
+ *     user="lance",
+ *     password="secret"
+ * )
+ * }
  * <p>
  * Using a {@code URL}:
  * <br>
- * <pre>
- *  &#064;DataSourceDefinition(name="java:global/MyApp/MyDataSource",
- *    className="org.apache.derby.jdbc.ClientDataSource",
- *    url="jdbc:derby://localhost:1527/myDB",
- *    user="lance",
- *    password="secret"
+ * {@snippet :
+ * @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
+ *     className="org.apache.derby.jdbc.ClientDataSource",
+ *     url="jdbc:derby://localhost:1527/myDB",
+ *     user="lance",
+ *     password="secret"
  * )
- * </pre>
+ * }
  * <p>
  * An example lookup of the DataSource from an Jakarta Enterprise Beans:
- * <pre>
- * &#064;Stateless
+ * {@snippet :
+ * @Stateless
  * public class MyStatelessEJB {
- *   &#064;Resource(lookup="java:global/MyApp/myDataSource")
- *    DataSource myDB;
- *      ...
+ *     @Resource(lookup="java:global/MyApp/myDataSource")
+ *     DataSource myDB;
+ *     ...
  * }
- * </pre>
- * <p>
+ * }
+ *
  * @see javax.sql.DataSource
  * @see javax.sql.XADataSource
  * @see javax.sql.ConnectionPoolDataSource
@@ -208,7 +207,7 @@
     /**
      * Isolation level for connections. The Isolation level
      * must be one of the following:
-     * <p>
+     *
      * <ul>
      * <li>Connection.TRANSACTION_NONE,
      * <li>Connection.TRANSACTION_READ_ UNCOMMITTED,
@@ -216,7 +215,7 @@
      * <li>Connection.TRANSACTION_REPEATABLE_READ,
      * <li>Connection.TRANSACTION_SERIALIZABLE
      *</ul>
-     * <p>
+     *
      * Default is vendor-specific.
      * @since 1.1
      */
@@ -281,14 +280,14 @@
     /**
      * Used to specify vendor-specific properties and less commonly
      * used {@code DataSource} properties such as:
-     * <p>
+     *
      * <ul>
      * <li>dataSourceName
      * <li>networkProtocol
      * <li>propertyCycle
      * <li>roleName
      * </ul>
-     * <p>
+     *
      *  Properties are specified using the format:
      *  <i>propertyName=propertyValue</i>  with one property per array element.
      * <p>