From b1f023ba543df190b1ae103b706d78a2114c560a Mon Sep 17 00:00:00 2001
From: Scott M Stark <starksm64@gmail.com>
Date: Tue, 23 May 2023 03:08:01 -0500
Subject: [PATCH] Address the javadoc errors under jdk17 (#672)

* Address the javadoc errors under jdk17, #671
* Add Java 17 to the actions matrix

Signed-off-by: Scott M Stark <starksm64@gmail.com>
---
 .github/workflows/ci-actions.yml                       |  3 +--
 api/src/main/java/jakarta/decorator/package-info.java  |  6 +++---
 .../java/jakarta/enterprise/context/package-info.java  |  6 +++---
 .../main/java/jakarta/enterprise/event/Observes.java   |  2 +-
 .../java/jakarta/enterprise/event/package-info.java    |  6 +++---
 .../jakarta/enterprise/inject/spi/package-info.java    | 10 +++++-----
 6 files changed, 16 insertions(+), 17 deletions(-)

diff --git a/.github/workflows/ci-actions.yml b/.github/workflows/ci-actions.yml
index 7cdcbf0a..0f29c5a6 100644
--- a/.github/workflows/ci-actions.yml
+++ b/.github/workflows/ci-actions.yml
@@ -11,8 +11,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java:
-          - 11
+        java: [ '11', '17' ]
     steps:
       - uses: actions/checkout@v2
       - name: Set up JDK ${{ matrix.java }}
diff --git a/api/src/main/java/jakarta/decorator/package-info.java b/api/src/main/java/jakarta/decorator/package-info.java
index 94bdde62..4610ed95 100644
--- a/api/src/main/java/jakarta/decorator/package-info.java
+++ b/api/src/main/java/jakarta/decorator/package-info.java
@@ -32,7 +32,7 @@
  * for which interceptors are optimized. Decorators are called 
  * after interceptors.</p>
  * 
- * <h3>Decorated types</h3>
+ * <h2>Decorated types</h2>
  * 
  * <p>The set of decorated types of a decorator includes all 
  * bean types of the managed bean that are Java interfaces, 
@@ -49,7 +49,7 @@
  * <p>A decorator may be an abstract class, and is not required to 
  * implement every method of every decorated type.</p>
  * 
- * <h3>Delegate injection points</h3>
+ * <h2>Delegate injection points</h2>
  * 
  * <p>All decorators have a 
  * {@linkplain jakarta.decorator.Delegate delegate injection point}.  
@@ -60,7 +60,7 @@
  * extend every decorated type. A decorator is not required to 
  * implement the type of the delegate injection point.</p>
  * 
- * <h3>Enabled decorators</h3>
+ * <h2>Enabled decorators</h2>
  *  
  * <p>By default, a bean archive has no enabled decorators. A 
  * decorator must be explicitly enabled by listing its bean class 
diff --git a/api/src/main/java/jakarta/enterprise/context/package-info.java b/api/src/main/java/jakarta/enterprise/context/package-info.java
index b2e2232d..86e701e4 100644
--- a/api/src/main/java/jakarta/enterprise/context/package-info.java
+++ b/api/src/main/java/jakarta/enterprise/context/package-info.java
@@ -29,7 +29,7 @@
  * bean</li>
  * </ul>
  * 
- * <h3>Built-in scopes</h3>
+ * <h2>Built-in scopes</h2>
  * 
  * <p>The following built-in scopes are provided:
  * {@link jakarta.enterprise.context.Dependent &#064;Dependent},
@@ -57,7 +57,7 @@
  * method invocations or to asynchronous processes such as JMS message 
  * listeners or EJB timer service timeouts.</p>
  * 
- * <h3>Normal scopes and pseudo-scopes</h3>
+ * <h2>Normal scopes and pseudo-scopes</h2>
  * 
  * <p>Most scopes are <em>normal scopes</em>. Normal scopes are declared 
  * using {@link jakarta.enterprise.context.NormalScope &#064;NormalScope}. 
@@ -80,7 +80,7 @@
  * {@link jakarta.enterprise.context.Dependent &#064;Dependent} and
  * {@link jakarta.inject.Singleton &#064;Singleton} pseudo-scopes.</p>
  * 
- * <h3>Contextual and injected reference validity</h3>
+ * <h2>Contextual and injected reference validity</h2>
  * 
  * <p>A reference to a bean obtained from the container via {@linkplain 
  * jakarta.enterprise.inject.Instance programmatic lookup} is called a 
diff --git a/api/src/main/java/jakarta/enterprise/event/Observes.java b/api/src/main/java/jakarta/enterprise/event/Observes.java
index 20175f55..c1d9ea4c 100644
--- a/api/src/main/java/jakarta/enterprise/event/Observes.java
+++ b/api/src/main/java/jakarta/enterprise/event/Observes.java
@@ -105,8 +105,8 @@
      * 
      * <p>
      * By default, the observer method is notified when the event is fired.
-     * @return phase of the transaction
      * </p>
+     * @return phase of the transaction
      */
     public TransactionPhase during() default TransactionPhase.IN_PROGRESS;
 }
diff --git a/api/src/main/java/jakarta/enterprise/event/package-info.java b/api/src/main/java/jakarta/enterprise/event/package-info.java
index d3e87e0a..1f0f9450 100644
--- a/api/src/main/java/jakarta/enterprise/event/package-info.java
+++ b/api/src/main/java/jakarta/enterprise/event/package-info.java
@@ -37,7 +37,7 @@
  * <p>The {@link jakarta.enterprise.event.Event} interface is used to 
  * fire events.</p>
  * 
- * <h3>Event objects and event types</h3>
+ * <h2>Event objects and event types</h2>
  * 
  * <p>The event object acts as a payload, to propagate state from 
  * producer to consumer. An event object is an instance of a concrete 
@@ -47,13 +47,13 @@
  * interfaces of the runtime class of the event object. An event type 
  * may not contain a type variable.</p>
  * 
- * <h3>Event qualifiers</h3>
+ * <h2>Event qualifiers</h2>
  * 
  * <p>The event qualifiers act as topic selectors, allowing the consumer 
  * to narrow the set of events it observes. An event qualifier may be an
  * instance of any {@linkplain jakarta.inject.Qualifier qualifier type}.</p>
  * 
- * <h3>Observer methods</h3>
+ * <h2>Observer methods</h2>
  * 
  * <p>An {@linkplain jakarta.enterprise.event.Observes observer method} 
  * allows the application to receive and respond synchronously to event notifications.
diff --git a/api/src/main/java/jakarta/enterprise/inject/spi/package-info.java b/api/src/main/java/jakarta/enterprise/inject/spi/package-info.java
index f4ec428d..cb611f1f 100644
--- a/api/src/main/java/jakarta/enterprise/inject/spi/package-info.java
+++ b/api/src/main/java/jakarta/enterprise/inject/spi/package-info.java
@@ -28,7 +28,7 @@
  * metadata from some other source</li>
  * </ul>
  * 
- * <h3>The <code>BeanManager</code> object</h3>
+ * <h2>The <code>BeanManager</code> object</h2>
  * 
  * <p>Portable extensions sometimes interact directly with the container 
  * via programmatic API call. The interface 
@@ -36,7 +36,7 @@
  * for obtaining contextual references for beans, along with many other 
  * operations of use to portable extensions.</p>
  * 
- * <h3>Container lifecycle events</h3>
+ * <h2>Container lifecycle events</h2>
  * 
  * <p>During the application initialization process, the container fires 
  * a series of {@linkplain jakarta.enterprise.event events}, allowing 
@@ -51,7 +51,7 @@
  * {@link jakarta.enterprise.inject.spi.AfterDeploymentValidation} and
  * {@link jakarta.enterprise.inject.spi.BeforeShutdown}.</p>
  * 
- * <h3>Interfaces representing enabled beans</h3>
+ * <h2>Interfaces representing enabled beans</h2>
  * 
  * <p>The interfaces 
  * {@link jakarta.enterprise.inject.spi.Bean},
@@ -83,7 +83,7 @@
  * observing the event type
  * {@link jakarta.enterprise.inject.spi.ProcessObserverMethod}.</p>
  * 
- * <h3>Alternate metadata sources</h3>
+ * <h2>Alternate metadata sources</h2>
  * 
  * <p>A portable extension may provide an alternative metadata 
  * source, such as configuration by XML.</p>
@@ -104,7 +104,7 @@
  * {@linkplain jakarta.enterprise.inject.spi.ProcessAnnotatedType#setAnnotatedType(AnnotatedType)
  * wrapping} the {@link jakarta.enterprise.inject.spi.AnnotatedType}.</p>
  * 
- * <h3><code>Producer</code> and <code>InjectionTarget</code></h3>
+ * <h2><code>Producer</code> and <code>InjectionTarget</code></h2>
  * 
  * <p>The interfaces {@link jakarta.enterprise.inject.spi.Producer} and
  * {@link jakarta.enterprise.inject.spi.InjectionTarget} abstract the