Skip to content

Commit 62206ad

Browse files
committed
Apply @snippet to javadoc,
also fixes couple errors in sample code throught the docs Signed-off-by: Lukas Jungmann <[email protected]>
1 parent 2156e6a commit 62206ad

33 files changed

+1486
-1556
lines changed

.github/workflows/maven.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ jobs:
2323

2424
strategy:
2525
matrix:
26-
java_version: [ 11, 17, 21 ]
26+
java_version: [ 21 ]
2727

2828
steps:
2929
- name: Checkout for build

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

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2005, 2021 Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2005, 2024 Oracle and/or its affiliates. All rights reserved.
33
*
44
* This program and the accompanying materials are made available under the
55
* terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -242,9 +242,9 @@ protected Binder() {}
242242
*
243243
* <p>
244244
* This is a convenience method of:
245-
* <pre>
246-
* updateXML( jaxbObject, getXMLNode(jaxbObject));
247-
* </pre>
245+
* {@snippet :
246+
* updateXML( jaxbObject, getXMLNode(jaxbObject));
247+
* }
248248
*
249249
* @param jaxbObject the XML Binding object
250250
*

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

+16-19
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2003, 2021 Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2003, 2024 Oracle and/or its affiliates. All rights reserved.
33
*
44
* This program and the accompanying materials are made available under the
55
* terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -28,23 +28,21 @@
2828
* implementation of parse and print methods. These methods are invoked by
2929
* custom parse and print methods. For example, the binding of xsd:dateTime
3030
* to a long can be customized using parse and print methods as follows:
31-
* <blockquote>
32-
* <pre>
33-
* // Customized parse method
34-
* public long myParseCal( String dateTimeString ) {
35-
* java.util.Calendar cal = DatatypeConverter.parseDateTime(dateTimeString);
36-
* long longval = convert_calendar_to_long(cal); //application specific
37-
* return longval;
38-
* }
39-
*
40-
* // Customized print method
41-
* public String myPrintCal( Long longval ) {
42-
* java.util.Calendar cal = convert_long_to_calendar(longval) ; //application specific
43-
* String dateTimeString = DatatypeConverter.printDateTime(cal);
44-
* return dateTimeString;
45-
* }
46-
* </pre>
47-
* </blockquote>
31+
* {@snippet :
32+
* // Customized parse method
33+
* public long myParseCal( String dateTimeString ) {
34+
* java.util.Calendar cal = DatatypeConverter.parseDateTime(dateTimeString);
35+
* long longval = convert_calendar_to_long(cal); //application specific
36+
* return longval;
37+
* }
38+
*
39+
* // Customized print method
40+
* public String myPrintCal( Long longval ) {
41+
* java.util.Calendar cal = convert_long_to_calendar(longval) ; //application specific
42+
* String dateTimeString = DatatypeConverter.printDateTime(cal);
43+
* return dateTimeString;
44+
* }
45+
* }
4846
* <p>
4947
* There is a static parse and print method corresponding to each parse and
5048
* print method respectively in the {@link DatatypeConverterInterface
@@ -75,7 +73,6 @@
7573
* @see PrintConversionEvent
7674
* @since 1.6, JAXB 1.0
7775
*/
78-
7976
final public class DatatypeConverter {
8077

8178
// delegate to this instance of DatatypeConverter

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

+35-35
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2003, 2022 Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2003, 2024 Oracle and/or its affiliates. All rights reserved.
33
*
44
* This program and the accompanying materials are made available under the
55
* terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -67,13 +67,13 @@
6767
* application is able to unmarshal XML documents that are instances of
6868
* any of the schemas listed in the {@code contextPath}. For example:
6969
*
70-
* <pre>
71-
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
72-
* Unmarshaller u = jc.createUnmarshaller();
73-
* FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
74-
* BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
75-
* BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
76-
* </pre>
70+
* {@snippet :
71+
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
72+
* Unmarshaller u = jc.createUnmarshaller();
73+
* FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
74+
* BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
75+
* BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
76+
* }
7777
*
7878
* <p>
7979
* The client application may also generate Java content trees explicitly rather
@@ -91,10 +91,10 @@
9191
* order to create objects of that type, the client application would use the
9292
* factory method like this:
9393
*
94-
* <pre>
95-
* com.acme.foo.PurchaseOrder po =
96-
* com.acme.foo.ObjectFactory.createPurchaseOrder();
97-
* </pre>
94+
* {@snippet :
95+
* com.acme.foo.PurchaseOrder po =
96+
* com.acme.foo.ObjectFactory.createPurchaseOrder();
97+
* }
9898
*
9999
* <p>
100100
* Once the client application has an instance of the the schema derived object,
@@ -128,17 +128,17 @@
128128
* Here is a simple example that unmarshals an XML document and then marshals
129129
* it back out:
130130
*
131-
* <pre>
132-
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
131+
* {@snippet :
132+
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
133133
*
134-
* // unmarshal from foo.xml
135-
* Unmarshaller u = jc.createUnmarshaller();
136-
* FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
134+
* // unmarshal from foo.xml
135+
* Unmarshaller u = jc.createUnmarshaller();
136+
* FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
137137
*
138-
* // marshal to System.out
139-
* Marshaller m = jc.createMarshaller();
140-
* m.marshal( fooObj, System.out );
141-
* </pre>
138+
* // marshal to System.out
139+
* Marshaller m = jc.createMarshaller();
140+
* m.marshal( fooObj, System.out );
141+
* }
142142
*
143143
*
144144
* <h3>Validation</h3>
@@ -416,13 +416,13 @@ public static JAXBContext newInstance( String contextPath,
416416
// * For example, in the following Java code, if you do
417417
// * {@code newInstance(Foo.class)}, the newly created {@link JAXBContext}
418418
// * will recognize both {@code Foo} and {@code Bar}, but not {@code Zot}:
419-
// * <pre>
420-
// * class Foo {
421-
// * Bar b;
419+
// * {@snippet :
420+
// * class Foo {
421+
// * Bar b;
422+
// * }
423+
// * class Bar { int x; }
424+
// * class Zot extends Bar { int y; }
422425
// * }
423-
// * class Bar { int x; }
424-
// * class Zot extends Bar { int y; }
425-
// * </pre>
426426
// *
427427
// * Therefore, a typical client application only needs to specify the
428428
// * top-level classes, but it needs to be careful.
@@ -491,15 +491,15 @@ public static JAXBContext newInstance( String contextPath,
491491
* For example, in the following Java code, if you do
492492
* {@code newInstance(Foo.class)}, the newly created {@link JAXBContext}
493493
* will recognize both {@code Foo} and {@code Bar}, but not {@code Zot} or {@code FooBar}:
494-
* <pre>
495-
* class Foo {
496-
* &#64;XmlTransient FooBar c;
497-
* Bar b;
494+
* {@snippet :
495+
* class Foo {
496+
* @XmlTransient FooBar c;
497+
* Bar b;
498+
* }
499+
* class Bar { int x; }
500+
* class Zot extends Bar { int y; }
501+
* class FooBar { }
498502
* }
499-
* class Bar { int x; }
500-
* class Zot extends Bar { int y; }
501-
* class FooBar { }
502-
* </pre>
503503
*
504504
* Therefore, a typical client application only needs to specify the
505505
* top-level classes, but it needs to be careful.

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

+57-81
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2003, 2021 Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2003, 2024 Oracle and/or its affiliates. All rights reserved.
33
*
44
* This program and the accompanying materials are made available under the
55
* terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -24,114 +24,92 @@
2424
*
2525
* <p>
2626
* <i>Assume the following setup code for all following code fragments:</i>
27-
* <blockquote>
28-
* <pre>
29-
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
30-
* Unmarshaller u = jc.createUnmarshaller();
31-
* Object element = u.unmarshal( new File( "foo.xml" ) );
32-
* Marshaller m = jc.createMarshaller();
33-
* </pre>
34-
* </blockquote>
27+
* {@snippet :
28+
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
29+
* Unmarshaller u = jc.createUnmarshaller();
30+
* Object element = u.unmarshal( new File( "foo.xml" ) );
31+
* Marshaller m = jc.createMarshaller();
32+
* }
3533
*
3634
* <p>
3735
* Marshalling to a File:
38-
* <blockquote>
39-
* <pre>
40-
* OutputStream os = new FileOutputStream( "nosferatu.xml" );
41-
* m.marshal( element, os );
42-
* </pre>
43-
* </blockquote>
36+
* {@snippet :
37+
* OutputStream os = new FileOutputStream( "nosferatu.xml" );
38+
* m.marshal( element, os );
39+
* }
4440
*
4541
* <p>
4642
* Marshalling to a SAX ContentHandler:
47-
* <blockquote>
48-
* <pre>
49-
* // assume MyContentHandler instanceof ContentHandler
50-
* m.marshal( element, new MyContentHandler() );
51-
* </pre>
52-
* </blockquote>
43+
* {@snippet :
44+
* // assume MyContentHandler instanceof ContentHandler
45+
* m.marshal( element, new MyContentHandler() );
46+
* }
5347
*
5448
* <p>
5549
* Marshalling to a DOM Node:
56-
* <blockquote>
57-
* <pre>
58-
* DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
59-
* dbf.setNamespaceAware(true);
60-
* DocumentBuilder db = dbf.newDocumentBuilder();
61-
* Document doc = db.newDocument();
50+
* {@snippet :
51+
* DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
52+
* dbf.setNamespaceAware(true);
53+
* DocumentBuilder db = dbf.newDocumentBuilder();
54+
* Document doc = db.newDocument();
6255
*
63-
* m.marshal( element, doc );
64-
* </pre>
65-
* </blockquote>
56+
* m.marshal( element, doc );
57+
* }
6658
*
6759
* <p>
6860
* Marshalling to a java.io.OutputStream:
69-
* <blockquote>
70-
* <pre>
71-
* m.marshal( element, System.out );
72-
* </pre>
73-
* </blockquote>
61+
* {@snippet :
62+
* m.marshal( element, System.out );
63+
* }
7464
*
7565
* <p>
7666
* Marshalling to a java.io.Writer:
77-
* <blockquote>
78-
* <pre>
79-
* m.marshal( element, new PrintWriter( System.out ) );
80-
* </pre>
81-
* </blockquote>
67+
* {@snippet :
68+
* m.marshal( element, new PrintWriter( System.out ) );
69+
* }
8270
*
8371
* <p>
8472
* Marshalling to a javax.xml.transform.SAXResult:
85-
* <blockquote>
86-
* <pre>
87-
* // assume MyContentHandler instanceof ContentHandler
88-
* SAXResult result = new SAXResult( new MyContentHandler() );
73+
* {@snippet :
74+
* // assume MyContentHandler instanceof ContentHandler
75+
* SAXResult result = new SAXResult( new MyContentHandler() );
8976
*
90-
* m.marshal( element, result );
91-
* </pre>
92-
* </blockquote>
77+
* m.marshal( element, result );
78+
* }
9379
*
9480
* <p>
9581
* Marshalling to a javax.xml.transform.DOMResult:
96-
* <blockquote>
97-
* <pre>
98-
* DOMResult result = new DOMResult();
82+
* {@snippet :
83+
* DOMResult result = new DOMResult();
9984
*
100-
* m.marshal( element, result );
101-
* </pre>
102-
* </blockquote>
85+
* m.marshal( element, result );
86+
* }
10387
*
10488
* <p>
10589
* Marshalling to a javax.xml.transform.StreamResult:
106-
* <blockquote>
107-
* <pre>
108-
* StreamResult result = new StreamResult( System.out );
90+
* {@snippet :
91+
* StreamResult result = new StreamResult( System.out );
10992
*
110-
* m.marshal( element, result );
111-
* </pre>
112-
* </blockquote>
93+
* m.marshal( element, result );
94+
* }
11395
*
11496
* <p>
11597
* Marshalling to a javax.xml.stream.XMLStreamWriter:
116-
* <blockquote>
117-
* <pre>
118-
* XMLStreamWriter xmlStreamWriter =
119-
* XMLOutputFactory.newInstance().createXMLStreamWriter( ... );
98+
* {@snippet :
99+
* XMLStreamWriter xmlStreamWriter =
100+
* XMLOutputFactory.newInstance().createXMLStreamWriter( ... );
120101
*
121-
* m.marshal( element, xmlStreamWriter );
122-
* </pre>
123-
* </blockquote>
102+
* m.marshal( element, xmlStreamWriter );
103+
* }
124104
*
125105
* <p>
126106
* Marshalling to a javax.xml.stream.XMLEventWriter:
127-
* <blockquote>
128-
* <pre>
129-
* XMLEventWriter xmlEventWriter =
130-
* XMLOutputFactory.newInstance().createXMLEventWriter( ... );
107+
* {@snippet :
108+
* XMLEventWriter xmlEventWriter =
109+
* XMLOutputFactory.newInstance().createXMLEventWriter( ... );
131110
*
132-
* m.marshal( element, xmlEventWriter );
133-
* </pre>
134-
* </blockquote>
111+
* m.marshal( element, xmlEventWriter );
112+
* }
135113
*
136114
* <p>
137115
* <a id="elementMarshalling"></a>
@@ -269,15 +247,13 @@
269247
* <p>
270248
* Class defined event callback methods allow any Jakarta XML Binding mapped class to specify
271249
* its own specific callback methods by defining methods with the following method signatures:
272-
* <blockquote>
273-
* <pre>
274-
* // Invoked by Marshaller after it has created an instance of this object.
275-
* boolean beforeMarshal(Marshaller);
250+
* {@snippet :
251+
* // Invoked by Marshaller after it has created an instance of this object.
252+
* boolean beforeMarshal(Marshaller);
276253
*
277-
* // Invoked by Marshaller after it has marshalled all properties of this object.
278-
* void afterMarshal(Marshaller);
279-
* </pre>
280-
* </blockquote>
254+
* // Invoked by Marshaller after it has marshalled all properties of this object.
255+
* void afterMarshal(Marshaller);
256+
* }
281257
* The class defined event callback methods should be used when the callback method requires
282258
* access to non-public methods and/or fields of the class.
283259
* <p>

0 commit comments

Comments
 (0)