src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -43,16 +43,20 @@
  * @see javax.xml.stream.events.EndDocument
  * @see javax.xml.stream.events.DTD
  * @since 1.6
  */
 public abstract class XMLEventFactory {
-  protected XMLEventFactory(){}
-
     static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory";
     static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl";
 
    /**
+     * Protected constructor to prevent instantiation.
+     * Use {@link #newFactory()} instead.
+     */
+    protected XMLEventFactory(){}
+
+   /**
    * Creates a new instance of the {@code XMLEventFactory} builtin
    * system-default implementation.
    *
    * @return A new instance of the {@code XMLEventFactory} builtin
    *         system-default implementation.

@@ -64,10 +68,12 @@
   }
 
   /**
    * Creates a new instance of the factory in exactly the same manner as the
    * {@link #newFactory()} method.
+   *
+   * @return an instance of the {@code XMLEventFactory}
    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
    */
   public static XMLEventFactory newInstance()
     throws FactoryConfigurationError
   {

@@ -124,10 +130,11 @@
    * </ul>
    * <p>
    *   Once an application has obtained a reference to a XMLEventFactory it
    *   can use the factory to configure and obtain stream instances.
    *
+   * @return an instance of the {@code XMLEventFactory}
    * @throws FactoryConfigurationError in case of {@linkplain
    *   java.util.ServiceConfigurationError service configuration error} or if
    *   the implementation is not available or cannot be instantiated.
    */
   public static XMLEventFactory newFactory()

@@ -472,13 +479,13 @@
    * @return an EntityReference event
    */
   public abstract EntityReference createEntityReference(String name,
                                                         EntityDeclaration declaration);
   /**
-   * Create a comment
+   * Create a comment.
    * @param text The text of the comment
-   * a Comment event
+   * @return a Comment event
    */
   public abstract Comment createComment(String text);
 
   /**
    * Create a processing instruction