Javadoc improvements wrt #2211

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/databind/ObjectMapper.java

@@ -2367,11 +2367,14 @@ public <T> T readValue(JsonParser p, JavaType valueType)
     }
 
     /**
-     * Method to deserialize JSON content as tree expressed
-     * using set of {@link JsonNode} instances. Returns
-     * root of the resulting tree (where root can consist
-     * of just a single node if the current event is a
-     * value event, not container).
+     * Method to deserialize JSON content as a tree {@link JsonNode}.
+     * Returns {@link JsonNode} that represents the root of the resulting tree, if there
+     * was content to read, or {@code null} if no more content is accessible
+     * via passed {@link JsonParser}.
+     *<p>
+     * NOTE! Behavior with end-of-input (no more content) differs between this
+     * {@code readTree} method, and all other methods that take input source: latter
+     * will return "missing node", NOT {@code null}
      * 
      * @return a {@link JsonNode}, if valid JSON content found; null
      *   if input has no content to bind -- note, however, that if
@@ -2523,105 +2526,40 @@ public JsonNode readTree(InputStream in) throws IOException
     }
 
     /**
-     * Method to deserialize JSON content as tree expressed
-     * using set of {@link JsonNode} instances.
-     * Returns root of the resulting tree (where root can consist
-     * of just a single node if the current event is a
-     * value event, not container).
-     *<p>
-     * If a low-level I/O problem (missing input, network error) occurs,
-     * a {@link IOException} will be thrown.
-     * If a parsing problem occurs (invalid JSON),
-     * {@link JsonParseException} will be thrown.
-     * If no content is found from input (end-of-input), Java
-     * <code>null</code> will be returned.
-     *
-     * @param r Reader used to read JSON content
-     *   for building the JSON tree.
-     * 
-     * @return a {@link JsonNode}, if valid JSON content found; null
-     *   if input has no content to bind -- note, however, that if
-     *   JSON <code>null</code> token is found, it will be represented
-     *   as a non-null {@link JsonNode} (one that returns <code>true</code>
-     *   for {@link JsonNode#isNull()}
+     * Same as {@link #readTree(InputStream)} except content accessed through
+     * passed-in {@link Reader}
      */
     public JsonNode readTree(Reader r) throws IOException {
         return _readTreeAndClose(_jsonFactory.createParser(r));
     }
 
     /**
-     * Method to deserialize JSON content as tree expressed using set of {@link JsonNode} instances.
-     * Returns root of the resulting tree (where root can consist of just a single node if the current
-     * event is a value event, not container).
-     *<p>
-     * If a low-level I/O problem (missing input, network error) occurs,
-     * a {@link IOException} will be thrown.
-     * If a parsing problem occurs (invalid JSON),
-     * {@link JsonParseException} will be thrown.
-     * If no content is found from input (end-of-input), Java
-     * <code>null</code> will be returned.
-     *
-     * @param content JSON content to parse to build the JSON tree.
-     * 
-     * @return a {@link JsonNode}, if valid JSON content found; null
-     *   if input has no content to bind -- note, however, that if
-     *   JSON <code>null</code> token is found, it will be represented
-     *   as a non-null {@link JsonNode} (one that returns <code>true</code>
-     *   for {@link JsonNode#isNull()}
-     *
-     * @throws JsonParseException if underlying input contains invalid content
-     *    of type {@link JsonParser} supports (JSON for default case)
+     * Same as {@link #readTree(InputStream)} except content read from
+     * passed-in {@link String}
      */
     public JsonNode readTree(String content) throws IOException {
         return _readTreeAndClose(_jsonFactory.createParser(content));
     }
 
     /**
-     * Method to deserialize JSON content as tree expressed using set of {@link JsonNode} instances.
-     * Returns root of the resulting tree (where root can consist of just a single node if the current
-     * event is a value event, not container).
-     *
-     * @param content JSON content to parse to build the JSON tree.
-     * 
-     * @return a {@link JsonNode}, if valid JSON content found; null
-     *   if input has no content to bind -- note, however, that if
-     *   JSON <code>null</code> token is found, it will be represented
-     *   as a non-null {@link JsonNode} (one that returns <code>true</code>
-     *   for {@link JsonNode#isNull()}
-     *
-     * @throws JsonParseException if underlying input contains invalid content
-     *    of type {@link JsonParser} supports (JSON for default case)
+     * Same as {@link #readTree(InputStream)} except content read from
+     * passed-in byte array.
      */
     public JsonNode readTree(byte[] content) throws IOException {
         return _readTreeAndClose(_jsonFactory.createParser(content));
     }
 
     /**
-     * @since 2.10
+     * Same as {@link #readTree(InputStream)} except content read from
+     * passed-in byte array.
      */
     public JsonNode readTree(byte[] content, int offset, int len) throws IOException {
         return _readTreeAndClose(_jsonFactory.createParser(content, offset, len));
     }
 
     /**
-     * Method to deserialize JSON content as tree expressed using set of {@link JsonNode} instances.
-     * Returns root of the resulting tree (where root can consist of just a single node if the current
-     * event is a value event, not container).
-     *
-     * @param file File of which contents to parse as JSON for building a tree instance
-     * 
-     * @return a {@link JsonNode}, if valid JSON content found; null
-     *   if input has no content to bind -- note, however, that if
-     *   JSON <code>null</code> token is found, it will be represented
-     *   as a non-null {@link JsonNode} (one that returns <code>true</code>
-     *   for {@link JsonNode#isNull()}
-     * 
-     * @throws IOException if a low-level I/O problem (unexpected end-of-input,
-     *   network error) occurs (passed through as-is without additional wrapping -- note
-     *   that this is one case where {@link DeserializationFeature#WRAP_EXCEPTIONS}
-     *   does NOT result in wrapping of exception even if enabled)
-     * @throws JsonParseException if underlying input contains invalid content
-     *    of type {@link JsonParser} supports (JSON for default case)
+     * Same as {@link #readTree(InputStream)} except content read from
+     * passed-in {@link File}.
      */
     public JsonNode readTree(File file)
         throws IOException, JsonProcessingException
@@ -2630,24 +2568,8 @@ public JsonNode readTree(File file)
     }
 
     /**
-     * Method to deserialize JSON content as tree expressed using set of {@link JsonNode} instances.
-     * Returns root of the resulting tree (where root can consist of just a single node if the current
-     * event is a value event, not container).
-     *
-     * @param source URL to use for fetching contents to parse as JSON for building a tree instance
-     * 
-     * @return a {@link JsonNode}, if valid JSON content found; null
-     *   if input has no content to bind -- note, however, that if
-     *   JSON <code>null</code> token is found, it will be represented
-     *   as a non-null {@link JsonNode} (one that returns <code>true</code>
-     *   for {@link JsonNode#isNull()}
-     * 
-     * @throws IOException if a low-level I/O problem (unexpected end-of-input,
-     *   network error) occurs (passed through as-is without additional wrapping -- note
-     *   that this is one case where {@link DeserializationFeature#WRAP_EXCEPTIONS}
-     *   does NOT result in wrapping of exception even if enabled)
-     * @throws JsonParseException if underlying input contains invalid content
-     *    of type {@link JsonParser} supports (JSON for default case)
+     * Same as {@link #readTree(InputStream)} except content read from
+     * passed-in {@link URL}.
      */
     public JsonNode readTree(URL source) throws IOException {
         return _readTreeAndClose(_jsonFactory.createParser(source));

src/main/java/com/fasterxml/jackson/databind/ObjectReader.java

@@ -1149,6 +1149,13 @@ public JsonParser treeAsTokens(TreeNode n) {
      * Convenience method that binds content read using given parser, using
      * configuration of this reader, except that content is bound as
      * JSON tree instead of configured root value type.
+     * Returns {@link JsonNode} that represents the root of the resulting tree, if there
+     * was content to read, or {@code null} if no more content is accessible
+     * via passed {@link JsonParser}.
+     *<p>
+     * NOTE! Behavior with end-of-input (no more content) differs between this
+     * {@code readTree} method, and all other methods that take input source: latter
+     * will return "missing node", NOT {@code null}
      *<p>
      * Note: if an object was specified with {@link #withValueToUpdate}, it
      * will be ignored.
@@ -1316,6 +1323,14 @@ public <T> T readValue(DataInput src) throws IOException
     /**
      * Method that reads content from given input source,
      * using configuration of this reader, and binds it as JSON Tree.
+     * Returns {@link JsonNode} that represents the root of the resulting tree, if there
+     * was content to read, or "missing node" (instance of {@JsonNode} for which
+     * {@link JsonNode#isMissingNode()} returns true, and behaves otherwise similar to
+     * "null node") if no more content is accessible through passed-in input source.
+     *<p>
+     * NOTE! Behavior with end-of-input (no more content) differs between this
+     * {@code readTree} method, and {@link #readTree(JsonParser)} -- latter returns
+     * {@code null} for "no content" case.
      *<p>
      * Note that if an object was specified with a call to
      * {@link #withValueToUpdate(Object)}
@@ -1331,13 +1346,8 @@ public JsonNode readTree(InputStream in) throws IOException
     }
 
     /**
-     * Method that reads content from given input source,
-     * using configuration of this reader, and binds it as JSON Tree.
-     *<p>
-     * Note that if an object was specified with a call to
-     * {@link #withValueToUpdate(Object)}
-     * it will just be ignored; result is always a newly constructed
-     * {@link JsonNode} instance.
+     * Same as {@link #readTree(InputStream)} except content accessed through
+     * passed-in {@link Reader}
      */
     public JsonNode readTree(Reader r) throws IOException
     {
@@ -1348,13 +1358,8 @@ public JsonNode readTree(Reader r) throws IOException
     }
 
     /**
-     * Method that reads content from given JSON input String,
-     * using configuration of this reader, and binds it as JSON Tree.
-     *<p>
-     * Note that if an object was specified with a call to
-     * {@link #withValueToUpdate(Object)}
-     * it will just be ignored; result is always a newly constructed
-     * {@link JsonNode} instance.
+     * Same as {@link #readTree(InputStream)} except content read from
+     * passed-in {@link String}
      */
     public JsonNode readTree(String json) throws IOException
     {
@@ -1365,7 +1370,8 @@ public JsonNode readTree(String json) throws IOException
     }
 
     /**
-     * @since 2.10
+     * Same as {@link #readTree(InputStream)} except content read from
+     * passed-in byte array.
      */
     public JsonNode readTree(byte[] json) throws IOException
     {
@@ -1376,7 +1382,8 @@ public JsonNode readTree(byte[] json) throws IOException
     }
 
     /**
-     * @since 2.10
+     * Same as {@link #readTree(InputStream)} except content read from
+     * passed-in byte array.
      */
     public JsonNode readTree(byte[] json, int offset, int len) throws IOException
     {
@@ -1386,6 +1393,10 @@ public JsonNode readTree(byte[] json, int offset, int len) throws IOException
         return _bindAndCloseAsTree(_considerFilter(_parserFactory.createParser(json, offset, len), false));
     }
 
+    /**
+     * Same as {@link #readTree(InputStream)} except content read using
+     * passed-in {@link DataInput}.
+     */
     public JsonNode readTree(DataInput src) throws IOException
     {
         if (_dataFormatReaders != null) {