Fix javadoc errors when built with JDK 8

Author: kinmanc

api/src/main/java/javax/json/JsonArrayBuilder.java

@@ -63,7 +63,6 @@
  * multiple builder instances with the same configuration. This the preferred
  * way to create multiple instances.
  *
- * <a id="JsonArrayBuilderExample1"/>
  * The example code below shows how to build a {@code JsonArray} object
  * that represents the following JSON array:
  *

api/src/main/java/javax/json/JsonNumber.java

@@ -50,11 +50,11 @@
  * Implementations may use a {@link BigDecimal} object to store the numeric
  * value internally.
  * The {@code BigDecimal} object can be constructed from the following types:
- * {@link BigDecimal#BigDecimal(int) <code>int</code>},
- * {@link BigDecimal#BigDecimal(long) <code>long</code>},
- * {@link BigDecimal#BigDecimal(BigInteger) <code>BigInteger</code>},
- * {@link BigDecimal#valueOf(double) <code>double</code>}, and
- * {@link BigDecimal#BigDecimal(String) <code>String</code>}.
+ * <code>int</code> {@link BigDecimal#BigDecimal(int)},
+ * <code>long</code> {@link BigDecimal#BigDecimal(long)},
+ * <code>BigInteger</code> {@link BigDecimal#BigDecimal(BigInteger)},
+ * <code>double</code> {@link BigDecimal#valueOf(double)}, and
+ * <code>String</code> {@link BigDecimal#BigDecimal(String)}.
  * Some of the method semantics in this class are defined using the
  * {@code BigDecimal} semantics.
  *

api/src/main/java/javax/json/JsonObjectBuilder.java

@@ -64,7 +64,6 @@
  * multiple builder instances with the same configuration. This the preferred
  * way to create multiple instances.
  *
- * <a id="JsonObjectBuilderExample1"/>
  * The example code below shows how to build a {@code JsonObject} model that
  * represents the following JSON object:
  *
@@ -277,4 +276,4 @@ public interface JsonObjectBuilder {
      */
     JsonObject build();
 
-}
+}

api/src/main/java/javax/json/JsonReader.java

@@ -50,7 +50,6 @@
  * input sources ({@link java.io.InputStream} and {@link java.io.Reader}).
  *
  * <p>
- * <a id="JsonReaderExample1"/>
  * The following example demonstrates how to read an empty JSON array from
  * a string:
  * <pre>

api/src/main/java/javax/json/JsonWriter.java

@@ -50,7 +50,6 @@
  * output sources ({@link java.io.OutputStream} and {@link java.io.Writer}).
  *
  * <p>
- * <a id="JsonWriterExample1"/>
  * The following example demonstrates how write an empty JSON object:
  * <pre>
  * <code>
@@ -128,4 +127,4 @@ public interface JsonWriter extends  /*Auto*/Closeable {
     @Override
     void close();
 
-}
+}

api/src/main/java/javax/json/stream/JsonGenerator.java

@@ -98,8 +98,6 @@
  * </pre>
  *
  * {@code JsonGenerator} methods can be chained as in the following example:
- * <p>
- * <a id="JsonGeneratorExample3"/>
  * <pre>
  * <code>
  * generator
@@ -129,7 +127,6 @@
  * </pre>
  *
  * The example code above generates the following JSON (or equivalent):
- * <p>
  * <pre>
  * <code>
  * {
@@ -535,4 +532,4 @@ public interface JsonGenerator extends Flushable, /*Auto*/Closeable {
     @Override
     void flush();
 
-}
+}

api/src/main/java/javax/json/stream/JsonGeneratorFactory.java

@@ -76,6 +76,7 @@ public interface JsonGeneratorFactory {
      * The generator is configured with the factory configuration.
      *
      * @param writer i/o writer to which JSON is written
+     * @return the created JSON generator
      */
     JsonGenerator createGenerator(Writer writer);
 
@@ -85,6 +86,7 @@ public interface JsonGeneratorFactory {
      * The generator is configured with the factory's configuration.
      *
      * @param out i/o stream to which JSON is written
+     * @return the created JSON generator
      */
     JsonGenerator createGenerator(OutputStream out);
 
@@ -95,6 +97,7 @@ public interface JsonGeneratorFactory {
      *
      * @param out i/o stream to which JSON is written
      * @param charset a charset
+     * @return the created JSON generator
      */
     JsonGenerator createGenerator(OutputStream out, Charset charset);
 
@@ -109,4 +112,4 @@ public interface JsonGeneratorFactory {
      */
     Map<String, ?> getConfigInUse();
 
-}
+}

api/src/main/java/javax/json/stream/JsonParser.java

@@ -97,8 +97,6 @@
  * </pre>
  *
  * <p>
- * <a id="JsonParserExample2"/>
- * <p>
  * <b>For example</b>, for the following JSON:
  * <pre>
  * {
@@ -113,7 +111,6 @@
  * <p>calls to the method {@code next()} result in parse events at the specified
  * locations below (marked in bold):
  *
- * <p>
  * <pre>
  * {<B>START_OBJECT</B>
  *   "firstName"<B>KEY_NAME</B>: "John"<B>VALUE_STRING</B>, "lastName"<B>KEY_NAME</B>: "Smith"<B>VALUE_STRING</B>, "age"<B>KEY_NAME</B>: 25<B>VALUE_NUMBER</B>,
@@ -124,13 +121,11 @@
  * }<B>END_OBJECT</B>
  * </pre>
  *
- * <p>
  * The methods {@code next()} and {@code hasNext()} enable iteration over
  * parser events to process JSON data. {@code JsonParser} provides get methods
  * to obtain the value at the current state of the parser. For example, the
  * following code shows how to obtain the value "John" from the JSON above:
  *
- * <p>
  * <pre>
  * <code>
  * Event event = parser.next(); // START_OBJECT
@@ -222,6 +217,7 @@ enum Event {
      * @throws JsonParsingException if the parser encounters invalid JSON
      * when advancing to next state.
      * @throws java.util.NoSuchElementException if there are no more parsing
+     * @return the event for the next parsing state
      * states.
      */
     Event next();

api/src/main/java/javax/json/stream/JsonParserFactory.java

@@ -77,6 +77,7 @@ public interface JsonParserFactory {
      * Creates a JSON parser from a character stream.
      *
      * @param reader a i/o reader from which JSON is to be read
+     * @return the created JSON parser
      */
     JsonParser createParser(Reader reader);
 
@@ -86,6 +87,7 @@ public interface JsonParserFactory {
      * as specified in <a href="http://tools.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
      *
      * @param in i/o stream from which JSON is to be read
+     * @return the created JSON parser
      * @throws javax.json.JsonException if encoding cannot be determined
      *         or i/o error (IOException would be cause of JsonException)
      */
@@ -98,20 +100,23 @@ public interface JsonParserFactory {
      *
      * @param in i/o stream from which JSON is to be read
      * @param charset a charset
+     * @return the created JSON parser
      */
     JsonParser createParser(InputStream in, Charset charset);
 
     /**
      * Creates a JSON parser from the specified JSON object.
      *
      * @param obj a JSON object
+     * @return the created JSON parser
      */
     JsonParser createParser(JsonObject obj);
 
     /**
      * Creates a JSON parser from the specified JSON array.
      *
      * @param array a JSON array
+     * @return the created JSON parser
      */
     JsonParser createParser(JsonArray array);