src/java.xml/share/classes/javax/xml/stream/util/XMLEventAllocator.java

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 2009, 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

@@ -45,10 +45,11 @@
 public interface XMLEventAllocator {
 
   /**
    * This method creates an instance of the XMLEventAllocator. This
    * allows the XMLInputFactory to allocate a new instance per reader.
+   * @return an instance of the {@code XMLEventAllocator}
    */
   public XMLEventAllocator newInstance();
 
   /**
    * This method allocates an event given the current

@@ -56,10 +57,11 @@
    * does not have a one-to-one mapping between reader states
    * and events this method will return null.  This method
    * must not modify the state of the XMLStreamReader.
    * @param reader The XMLStreamReader to allocate from
    * @return the event corresponding to the current reader state
+   * @throws XMLStreamException if an error occurs
    */
   public XMLEvent allocate(XMLStreamReader reader)
     throws XMLStreamException;
 
   /**

@@ -70,10 +72,11 @@
    * consumer that was passed in.  This method can be used
    * to expand or contract reader states into event states.
    * This method may modify the state of the XMLStreamReader.
    * @param reader The XMLStreamReader to allocate from
    * @param consumer The XMLEventConsumer to add to.
+   * @throws XMLStreamException if an error occurs
    */
   public void allocate(XMLStreamReader reader, XMLEventConsumer consumer)
     throws XMLStreamException;
 
 }