Apply @snippet to javadoc,

also fixes couple errors in sample code throught the docs

Signed-off-by: Lukas Jungmann <[email protected]>

.github/workflows/maven.yml

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

api/src/main/java/jakarta/xml/bind/Binder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2021 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
@@ -242,9 +242,9 @@ protected Binder() {}
      *
      * <p>
      * This is a convenience method of:
-     * <pre>
-     * updateXML( jaxbObject, getXMLNode(jaxbObject));
-     * </pre>
+     * {@snippet :
+     *  updateXML( jaxbObject, getXMLNode(jaxbObject));
+     * }
      *
      * @param jaxbObject the XML Binding object
      *

api/src/main/java/jakarta/xml/bind/DatatypeConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -28,23 +28,21 @@
  * implementation of parse and print methods. These methods are invoked by 
  * custom parse and print methods. For example, the binding of xsd:dateTime 
  * to a long can be customized using parse and print methods as follows:
- * <blockquote>
- *    <pre>
- *    // Customized parse method 
- *    public long myParseCal( String dateTimeString ) {
- *        java.util.Calendar cal = DatatypeConverter.parseDateTime(dateTimeString);
- *        long longval = convert_calendar_to_long(cal); //application specific
- *        return longval;
- *    }
- *     
- *    // Customized print method
- *    public String myPrintCal( Long longval ) {
- *        java.util.Calendar cal = convert_long_to_calendar(longval) ; //application specific
- *        String dateTimeString = DatatypeConverter.printDateTime(cal);
- *        return dateTimeString;
- *    }
- *    </pre>
- * </blockquote>
+ * {@snippet :
+ *  // Customized parse method
+ *  public long myParseCal( String dateTimeString ) {
+ *      java.util.Calendar cal = DatatypeConverter.parseDateTime(dateTimeString);
+ *      long longval = convert_calendar_to_long(cal); //application specific
+ *      return longval;
+ *  }
+ *
+ *  // Customized print method
+ *  public String myPrintCal( Long longval ) {
+ *      java.util.Calendar cal = convert_long_to_calendar(longval) ; //application specific
+ *      String dateTimeString = DatatypeConverter.printDateTime(cal);
+ *      return dateTimeString;
+ *  }
+ * }
  * <p>
  * There is a static parse and print method corresponding to each parse and 
  * print method respectively in the {@link DatatypeConverterInterface 
@@ -75,7 +73,6 @@
  * @see PrintConversionEvent
  * @since 1.6, JAXB 1.0
  */
-
 final public class DatatypeConverter {
 
     // delegate to this instance of DatatypeConverter

api/src/main/java/jakarta/xml/bind/JAXBContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -67,13 +67,13 @@
  * application is able to unmarshal XML documents that are instances of
  * any of the schemas listed in the {@code contextPath}.  For example:
  *
- * <pre>
- *      JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
- *      Unmarshaller u = jc.createUnmarshaller();
- *      FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
- *      BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
- *      BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
- * </pre>
+ * {@snippet :
+ *  JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
+ *  Unmarshaller u = jc.createUnmarshaller();
+ *  FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
+ *  BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
+ *  BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
+ * }
  *
  * <p>
  * The client application may also generate Java content trees explicitly rather
@@ -91,10 +91,10 @@
  * order to create objects of that type, the client application would use the
  * factory method like this:
  *
- * <pre>
- *       com.acme.foo.PurchaseOrder po =
- *           com.acme.foo.ObjectFactory.createPurchaseOrder();
- * </pre>
+ * {@snippet :
+ *  com.acme.foo.PurchaseOrder po =
+ *      com.acme.foo.ObjectFactory.createPurchaseOrder();
+ * }
  *
  * <p>
  * Once the client application has an instance of the the schema derived object,
@@ -128,17 +128,17 @@
  * Here is a simple example that unmarshals an XML document and then marshals
  * it back out:
  *
- * <pre>
- *        JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
+ * {@snippet :
+ *  JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
  *
- *        // unmarshal from foo.xml
- *        Unmarshaller u = jc.createUnmarshaller();
- *        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
+ *  // unmarshal from foo.xml
+ *  Unmarshaller u = jc.createUnmarshaller();
+ *  FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
  *
- *        // marshal to System.out
- *        Marshaller m = jc.createMarshaller();
- *        m.marshal( fooObj, System.out );
- * </pre>
+ *  // marshal to System.out
+ *  Marshaller m = jc.createMarshaller();
+ *  m.marshal( fooObj, System.out );
+ * }
  *
  *
  * <h3>Validation</h3>
@@ -416,13 +416,13 @@ public static JAXBContext newInstance( String contextPath,
 //     * For example, in the following Java code, if you do
 //     * {@code newInstance(Foo.class)}, the newly created {@link JAXBContext}
 //     * will recognize both {@code Foo} and {@code Bar}, but not {@code Zot}:
-//     * <pre>
-//     * class Foo {
-//     *      Bar b;
+//     * {@snippet :
+//     *  class Foo {
+//     *       Bar b;
+//     *  }
+//     *  class Bar { int x; }
+//     *  class Zot extends Bar { int y; }
 //     * }
-//     * class Bar { int x; }
-//     * class Zot extends Bar { int y; }
-//     * </pre>
 //     *
 //     * Therefore, a typical client application only needs to specify the
 //     * top-level classes, but it needs to be careful.
@@ -491,15 +491,15 @@ public static JAXBContext newInstance( String contextPath,
      * For example, in the following Java code, if you do
      * {@code newInstance(Foo.class)}, the newly created {@link JAXBContext}
      * will recognize both {@code Foo} and {@code Bar}, but not {@code Zot} or {@code FooBar}:
-     * <pre>
-     * class Foo {
-     *      &#64;XmlTransient FooBar c;
-     *      Bar b;
+     * {@snippet :
+     *  class Foo {
+     *       @XmlTransient FooBar c;
+     *       Bar b;
+     *  }
+     *  class Bar { int x; }
+     *  class Zot extends Bar { int y; }
+     *  class FooBar { }
      * }
-     * class Bar { int x; }
-     * class Zot extends Bar { int y; }
-     * class FooBar { }
-     * </pre>
      *
      * Therefore, a typical client application only needs to specify the
      * top-level classes, but it needs to be careful.

api/src/main/java/jakarta/xml/bind/Marshaller.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -24,114 +24,92 @@
  *
  * <p>
  * <i>Assume the following setup code for all following code fragments:</i>
- * <blockquote>
- *    <pre>
- *       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
- *       Unmarshaller u = jc.createUnmarshaller();
- *       Object element = u.unmarshal( new File( "foo.xml" ) );
- *       Marshaller m = jc.createMarshaller();
- *    </pre>
- * </blockquote>
+ * {@snippet :
+ *  JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
+ *  Unmarshaller u = jc.createUnmarshaller();
+ *  Object element = u.unmarshal( new File( "foo.xml" ) );
+ *  Marshaller m = jc.createMarshaller();
+ * }
  *
  * <p>
  * Marshalling to a File:
- * <blockquote>
- *    <pre>
- *       OutputStream os = new FileOutputStream( "nosferatu.xml" );
- *       m.marshal( element, os );
- *    </pre>
- * </blockquote>
+ * {@snippet :
+ *  OutputStream os = new FileOutputStream( "nosferatu.xml" );
+ *  m.marshal( element, os );
+ * }
  *
  * <p>
  * Marshalling to a SAX ContentHandler:
- * <blockquote>
- *    <pre>
- *       // assume MyContentHandler instanceof ContentHandler
- *       m.marshal( element, new MyContentHandler() );
- *    </pre>
- * </blockquote>
+ * {@snippet :
+ *  // assume MyContentHandler instanceof ContentHandler
+ *  m.marshal( element, new MyContentHandler() );
+ * }
  *
  * <p>
  * Marshalling to a DOM Node:
- * <blockquote>
- *    <pre>
- *       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
- *       dbf.setNamespaceAware(true);
- *       DocumentBuilder db = dbf.newDocumentBuilder();
- *       Document doc = db.newDocument();
+ * {@snippet :
+ *  DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
+ *  dbf.setNamespaceAware(true);
+ *  DocumentBuilder db = dbf.newDocumentBuilder();
+ *  Document doc = db.newDocument();
  *
- *       m.marshal( element, doc );
- *    </pre>
- * </blockquote>
+ *  m.marshal( element, doc );
+ * }
  *
  * <p>
  * Marshalling to a java.io.OutputStream:
- * <blockquote>
- *    <pre>
- *       m.marshal( element, System.out );
- *    </pre>
- * </blockquote>
+ * {@snippet :
+ *  m.marshal( element, System.out );
+ * }
  *
  * <p>
  * Marshalling to a java.io.Writer:
- * <blockquote>
- *    <pre>
- *       m.marshal( element, new PrintWriter( System.out ) );
- *    </pre>
- * </blockquote>
+ * {@snippet :
+ *  m.marshal( element, new PrintWriter( System.out ) );
+ * }
  *
  * <p>
  * Marshalling to a javax.xml.transform.SAXResult:
- * <blockquote>
- *    <pre>
- *       // assume MyContentHandler instanceof ContentHandler
- *       SAXResult result = new SAXResult( new MyContentHandler() );
+ * {@snippet :
+ *  // assume MyContentHandler instanceof ContentHandler
+ *  SAXResult result = new SAXResult( new MyContentHandler() );
  *
- *       m.marshal( element, result );
- *    </pre>
- * </blockquote>
+ *  m.marshal( element, result );
+ * }
  *
  * <p>
  * Marshalling to a javax.xml.transform.DOMResult:
- * <blockquote>
- *    <pre>
- *       DOMResult result = new DOMResult();
+ * {@snippet :
+ *  DOMResult result = new DOMResult();
  *
- *       m.marshal( element, result );
- *    </pre>
- * </blockquote>
+ *  m.marshal( element, result );
+ * }
  *
  * <p>
  * Marshalling to a javax.xml.transform.StreamResult:
- * <blockquote>
- *    <pre>
- *       StreamResult result = new StreamResult( System.out );
+ * {@snippet :
+ *  StreamResult result = new StreamResult( System.out );
  *
- *       m.marshal( element, result );
- *    </pre>
- * </blockquote>
+ *  m.marshal( element, result );
+ * }
  *
  * <p>
  * Marshalling to a javax.xml.stream.XMLStreamWriter:
- * <blockquote>
- *    <pre>
- *       XMLStreamWriter xmlStreamWriter =
- *           XMLOutputFactory.newInstance().createXMLStreamWriter( ... );
+ * {@snippet :
+ *  XMLStreamWriter xmlStreamWriter =
+ *      XMLOutputFactory.newInstance().createXMLStreamWriter( ... );
  *
- *       m.marshal( element, xmlStreamWriter );
- *    </pre>
- * </blockquote>
+ *  m.marshal( element, xmlStreamWriter );
+ * }
  *
  * <p>
  * Marshalling to a javax.xml.stream.XMLEventWriter:
- * <blockquote>
- *    <pre>
- *       XMLEventWriter xmlEventWriter =
- *           XMLOutputFactory.newInstance().createXMLEventWriter( ... );
+ * {@snippet :
+ *  XMLEventWriter xmlEventWriter =
+ *      XMLOutputFactory.newInstance().createXMLEventWriter( ... );
  *
- *       m.marshal( element, xmlEventWriter );
- *    </pre>
- * </blockquote>
+ *  m.marshal( element, xmlEventWriter );
+ * }
  *
  * <p>
  * <a id="elementMarshalling"></a>
@@ -269,15 +247,13 @@
  * <p>
  * Class defined event callback methods allow any Jakarta XML Binding mapped class to specify
  * its own specific callback methods by defining methods with the following method signatures:
- * <blockquote>
- * <pre>
- *   // Invoked by Marshaller after it has created an instance of this object.
- *   boolean beforeMarshal(Marshaller);
+ * {@snippet :
+ *  // Invoked by Marshaller after it has created an instance of this object.
+ *  boolean beforeMarshal(Marshaller);
  *
- *   // Invoked by Marshaller after it has marshalled all properties of this object.
- *   void afterMarshal(Marshaller);
- * </pre>
- * </blockquote>
+ *  // Invoked by Marshaller after it has marshalled all properties of this object.
+ *  void afterMarshal(Marshaller);
+ * }
  * The class defined event callback methods should be used when the callback method requires
  * access to non-public methods and/or fields of the class.
  * <p>