Apply @snippet, fix typos, grammar

Signed-off-by: Lukas Jungmann <lukas.jungmann@oracle.com>

.github/workflows/maven.yml

@@ -23,7 +23,7 @@ jobs:
 
     strategy:
       matrix:
-        java_version: [ 17, 21 ]
+        java_version: [ 21 ]
 
     steps:
     - name: Checkout for build

api/src/main/java/jakarta/jws/HandlerChain.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -20,7 +20,7 @@
  * where embedding the handler configuration directly in the Java source is not appropriate; for example, where the
  * handler configuration needs to be shared across multiple Web Services, or where the handler chain consists of
  * handlers for multiple transports.
- *
+ * <p>
  * It is an error to combine this annotation with the @SOAPMessageHandlers annotation.
  *
  * @since 1.6

api/src/main/java/jakarta/jws/WebMethod.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -19,7 +19,7 @@
  * Customizes a method that is exposed as a Web Service operation.
  * The associated method must be public and its parameters return value,
  * and exceptions must follow the rules defined in Jakarta XML Web Services Specification, section 5.
- *
+ * <p>
  *  The method is not required to throw java.rmi.RemoteException.
  *
  * @since 1.6

api/src/main/java/jakarta/jws/WebParam.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -68,7 +68,7 @@ enum Mode {
     /**
      * The XML namespace for the parameter.
      * <p>
-     * Only used if the operation is document style or the paramater maps to a header.
+     * Only used if the operation is document style or the parameter maps to a header.
      * If the target namespace is set to "", this represents the empty namespace.
      *
      * @return the XML namespace for the parameter
@@ -93,10 +93,10 @@ enum Mode {
     Mode mode() default Mode.IN;
 
     /**
-     * If true, the parameter is pulled from a message header rather then the message body.
+     * If true, the parameter is pulled from a message header rather than the message body.
      *
      * @return value of {@code true} to pull the parameter from a message header
-     *         rather then the message body or {@code false} otherwise
+     *         rather than the message body or {@code false} otherwise
      */
     boolean header() default false;
 };

api/src/main/java/jakarta/jws/WebResult.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -69,10 +69,10 @@
     String targetNamespace() default "";
 
     /**
-     * If true, the result is pulled from a message header rather then the message body.
+     * If true, the result is pulled from a message header rather than the message body.
      *
      * @return value of {@code true} to pull the parameter from a message header
-     *         rather then the message body or {@code false} otherwise
+     *         rather than the message body or {@code false} otherwise
      * @since 2.0
      */
     boolean header() default false;

api/src/main/java/jakarta/jws/WebService.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -59,7 +59,7 @@
      * <i>This member-value is not allowed on endpoint interfaces.</i>
      *
      * @return the service name
-     * @specdefault The simple name of the Java class + Service".
+     * @specdefault The simple name of the Java class + Service.
      */
     String serviceName() default "";
 

api/src/main/java/jakarta/jws/soap/SOAPMessageHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -10,7 +10,8 @@
 
 package jakarta.jws.soap;
 
-@Deprecated public @interface SOAPMessageHandler {
+@Deprecated
+public @interface SOAPMessageHandler {
 
     /**
      * Name of the handler.Defaults to the name of the handler class.

api/src/main/java/jakarta/xml/ws/Action.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -33,65 +33,64 @@
  * <b>Example 1</b>: Specify explicit values for {@code Action} message addressing property
  * for {@code input} and {@code output} messages.
  *
- * <pre>
- * {@literal @}WebService(targetNamespace="http://example.com/numbers")
+ * {@snippet :
+ *  @WebService(targetNamespace="http://example.com/numbers")
  *  public class AddNumbersImpl {
- *     <b>{@literal @}Action(
- *          input="http://example.com/inputAction",
- *          output="http://example.com/outputAction")</b>
+ *      @Action(  // @highlight type="bold"
+ *          input="http://example.com/inputAction",  // @highlight type="bold"
+ *          output="http://example.com/outputAction")  // @highlight type="bold"
  *      public int addNumbers(int number1, int number2) {
  *          return number1 + number2;
  *      }
  *  }
- * </pre>
+ * }
  *
  * The generated WSDL looks like:
- * <pre> {@code
- *   <definitions targetNamespace="http://example.com/numbers" ...>
- *     ...
- *     <portType name="AddNumbersPortType">
- *       <operation name="AddNumbers">
- *         <input message="tns:AddNumbersInput" name="foo"
- *           <b>wsam:Action="http://example.com/inputAction"</b>/>
- *         <output message="tns:AddNumbersOutput" name="bar"
- *           <b>wsam:Action="http://example.com/outputAction"</b>/>
- *       </operation>
- *     </portType>
+ * {@snippet lang="XML" :
+ *  <definitions targetNamespace="http://example.com/numbers" ...>
+ *    ...
+ *    <portType name="AddNumbersPortType">
+ *      <operation name="AddNumbers">
+ *        <input message="tns:AddNumbersInput" name="foo"
+ *          wsam:Action="http://example.com/inputAction" /> // @highlight type="bold"
+ *        <output message="tns:AddNumbersOutput" name="bar"
+ *          wsam:Action="http://example.com/outputAction" /> // @highlight type="bold"
+ *      </operation>
+ *    </portType>
  *     ...
- *   </definitions>
+ *  </definitions>
  * }
- * </pre>
  *
  * <p>
  * <b>Example 2</b>: Specify explicit value for {@code Action} message addressing property
  * for only the {@code input} message. The {@code wsam:Action} values for the
  * WSDL {@code output} message are computed using the algorithm in the Jakarta XML Web Services specification.
  *
- * <pre>
- * {@literal @}WebService(targetNamespace="http://example.com/numbers")
+ * {@snippet :
+ *  @WebService(targetNamespace="http://example.com/numbers")
  *  public class AddNumbersImpl {
- *     <b>{@literal @}Action(input="http://example.com/inputAction")</b>
+ *      @Action(input="http://example.com/inputAction")  // @highlight type="bold"
  *      public int addNumbers(int number1, int number2) {
  *          return number1 + number2;
  *      }
  *  }
- * </pre>
+ * }
  *
  * The generated WSDL looks like:
- * <pre> {@code
- *   <definitions targetNamespace="http://example.com/numbers" ...>
- *     ...
- *     <portType name="AddNumbersPortType">
- *       <operation name="AddNumbers">
- *         <input message="tns:AddNumbersInput" name="foo"
- *           <b>wsam:Action="http://example.com/inputAction"</b>/>
- *         <output message="tns:AddNumbersOutput" name="bar"
- *           <b>wsam:Action="http://example.com/numbers/AddNumbersPortType/AddNumbersResponse"</b>/>
- *       </operation>
- *     </portType>
- *     ...
- *   </definitions>
- * }</pre>
+ * {@snippet lang="XML" :
+ *  <definitions targetNamespace="http://example.com/numbers" ...>
+ *    ...
+ *    <portType name="AddNumbersPortType">
+ *      <operation name="AddNumbers">
+ *        <input message="tns:AddNumbersInput" name="foo"
+ *          wsam:Action="http://example.com/inputAction" />  // @highlight type="bold"
+ *        <output message="tns:AddNumbersOutput" name="bar"
+ *          wsam:Action="http://example.com/numbers/AddNumbersPortType/AddNumbersResponse" />  // @highlight type="bold"
+ *      </operation>
+ *    </portType>
+ *    ...
+ *  </definitions>
+ * }
  *
  * It is legitimate to specify an explicit value for {@code Action} message addressing property for
  * {@code output} message only. In this case, {@code wsam:Action} value for the
@@ -106,7 +105,6 @@
  *
  * @since 1.6, JAX-WS 2.1
  */
-
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

api/src/main/java/jakarta/xml/ws/BindingProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -49,7 +49,7 @@ public interface BindingProvider {
 
     /**
      * Standard property: This boolean property is used by a service
-     * client to indicate whether or not it wants to participate in
+     * client to indicate whether it wants to participate in
      * a session with a service endpoint. If this property is set to
      * {@code true}, the service client indicates that it wants the session
      * to be maintained. If set to {@code false}, the session is not maintained.
@@ -61,7 +61,7 @@ public interface BindingProvider {
 
     /**
      * Standard property for SOAPAction. This boolean property
-     * indicates whether or not the value of the
+     * indicates whether the value of the
      * {@code jakarta.xml.ws.soap.http.soapaction.uri} property
      * is used for the value of the SOAPAction. The
      * default value of this property is {@code false} indicating
@@ -92,7 +92,7 @@ public interface BindingProvider {
     /**
      * Get the context that is used to initialize the message context
      * for request messages.
-     *
+     * <p>
      * Modifications to the request context do not affect the message context of
      * either synchronous or asynchronous operations that have already been
      * started.
@@ -103,7 +103,7 @@ public interface BindingProvider {
 
     /**
      * Get the context that resulted from processing a response message.
-     *
+     * <p>
      * The returned context is for the most recently completed synchronous
      * operation. Subsequent synchronous operation invocations overwrite the
      * response context. Asynchronous operations return their response context

api/src/main/java/jakarta/xml/ws/Dispatch.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -25,7 +25,7 @@
 public interface Dispatch<T> extends BindingProvider {
 
     /** Invoke a service operation synchronously.
-     *
+     * <p>
      * The client is responsible for ensuring that the {@code msg} object
      * when marshalled is formed according to the requirements of the protocol
      * binding in use.