yet more javadoc fixes

src/main/java/com/fasterxml/jackson/core/PrettyPrinter.java

@@ -51,11 +51,15 @@ public interface PrettyPrinter
      * Method called after a root-level value has been completely
      * output, and before another value is to be output.
      *<p>
-     * Default
-     * handling (without pretty-printing) will output a space, to
+     * Default handling (without pretty-printing) will output a space, to
      * allow values to be parsed correctly. Pretty-printer is
      * to output some other suitable and nice-looking separator
      * (tab(s), space(s), linefeed(s) or any combination thereof).
+     *
+     * @param gen Generator used for output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void writeRootValueSeparator(JsonGenerator gen) throws IOException;
 
@@ -70,6 +74,11 @@ public interface PrettyPrinter
      * Pretty-printer is
      * to output a curly bracket as well, but can surround that
      * with other (white-space) decoration.
+     *
+     * @param gen Generator used for output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void writeStartObject(JsonGenerator gen) throws IOException;
 
@@ -83,19 +92,28 @@ public interface PrettyPrinter
      * to output a curly bracket as well, but can surround that
      * with other (white-space) decoration.
      *
-     * @param nrOfEntries Number of direct members of the array that
+     * @param gen Generator used for output
+     * @param nrOfEntries Number of direct members of the Object that
      *   have been output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void writeEndObject(JsonGenerator gen, int nrOfEntries) throws IOException;
 
     /**
-     * Method called after an object entry (field:value) has been completely
+     * Method called after an Object entry (field:value) has been completely
      * output, and before another value is to be output.
      *<p>
      * Default handling (without pretty-printing) will output a single
      * comma to separate the two. Pretty-printer is
      * to output a comma as well, but can surround that with other
      * (white-space) decoration.
+     *
+     * @param gen Generator used for output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void writeObjectEntrySeparator(JsonGenerator gen) throws IOException;
 
@@ -107,6 +125,11 @@ public interface PrettyPrinter
      * colon to separate the two. Pretty-printer is
      * to output a colon as well, but can surround that with other
      * (white-space) decoration.
+     *
+     * @param gen Generator used for output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void writeObjectFieldValueSeparator(JsonGenerator gen) throws IOException;
 
@@ -121,6 +144,11 @@ public interface PrettyPrinter
      * Pretty-printer is
      * to output a bracket as well, but can surround that
      * with other (white-space) decoration.
+     *
+     * @param gen Generator used for output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void writeStartArray(JsonGenerator gen) throws IOException;
 
@@ -134,8 +162,12 @@ public interface PrettyPrinter
      * to output a bracket as well, but can surround that
      * with other (white-space) decoration.
      *
+     * @param gen Generator used for output
      * @param nrOfValues Number of direct members of the array that
      *   have been output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void writeEndArray(JsonGenerator gen, int nrOfValues) throws IOException;
 
@@ -147,14 +179,18 @@ public interface PrettyPrinter
      * comma to separate the two. Pretty-printer is
      * to output a comma as well, but can surround that with other
      * (white-space) decoration.
+     *
+     * @param gen Generator used for output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void writeArrayValueSeparator(JsonGenerator gen) throws IOException;
 
     /*
     /**********************************************************
-    /* Then events that by default do not produce any output
-    /* but that are often overridden to add white space
-    /* in pretty-printing mode
+    /* Then events that by default do not produce any output but that are
+    /* often overridden to add white space in pretty-printing mode
     /**********************************************************
      */
 
@@ -165,6 +201,11 @@ public interface PrettyPrinter
      *<p>
      * Default handling does not output anything, but pretty-printer
      * is free to add any white space decoration.
+     *
+     * @param gen Generator used for output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void beforeArrayValues(JsonGenerator gen) throws IOException;
 
@@ -176,6 +217,11 @@ public interface PrettyPrinter
      *<p>
      * Default handling does not output anything, but pretty-printer
      * is free to add any white space decoration.
+     *
+     * @param gen Generator used for output
+     *
+     * @throws IOException if there is either an underlying I/O problem or encoding
+     *    issue at format layer
      */
     void beforeObjectEntries(JsonGenerator gen) throws IOException;
 }

src/main/java/com/fasterxml/jackson/core/SerializableString.java

@@ -26,6 +26,8 @@ public interface SerializableString
     /**
      * Returns unquoted String that this object represents (and offers
      * serialized forms for)
+     *
+     * @return Unquoted String
      */
     String getValue();
 
@@ -35,6 +37,8 @@ public interface SerializableString
      *<pre>
      *   getValue().length();
      *</pre>
+     *
+     * @return Length of the String in characters
      */
     int charLength();
 
@@ -47,6 +51,8 @@ public interface SerializableString
     /**
      * Returns JSON quoted form of the String, as character array.
      * Result can be embedded as-is in textual JSON as property name or JSON String.
+     *
+     * @return JSON quoted form of the String as {@code char[]}
      */
     char[] asQuotedChars();
 
@@ -56,6 +62,8 @@ public interface SerializableString
      *<pre>
      * getValue().getBytes("UTF-8");
      *</pre>
+     *
+     * @return UTF-8 encoded version of String, without any escaping
      */
     byte[] asUnquotedUTF8();
 
@@ -65,6 +73,8 @@ public interface SerializableString
      *<pre>
      * new String(asQuotedChars()).getBytes("UTF-8");
      *</pre>
+     *
+     * @return UTF-8 encoded version of JSON-escaped String
      */
     byte[] asQuotedUTF8();
 
@@ -83,7 +93,10 @@ public interface SerializableString
      *  System.arraycopy(bytes, 0, buffer, offset, bytes.length);
      *  return bytes.length;
      *</pre>
-     * 
+     *
+     * @param buffer Buffer to append JSON-escaped String into
+     * @param offset Offset in {@code buffer} to append String at
+     *
      * @return Number of bytes appended, if successful, otherwise -1
      */
     int appendQuotedUTF8(byte[] buffer, int offset);
@@ -96,6 +109,9 @@ public interface SerializableString
      *  System.arraycopy(ch, 0, buffer, offset, ch.length);
      *  return ch.length;
      *</pre>
+     *
+     * @param buffer Buffer to append JSON-escaped String into
+     * @param offset Offset in {@code buffer} to append String at
      * 
      * @return Number of characters appended, if successful, otherwise -1
      */
@@ -109,12 +125,14 @@ public interface SerializableString
      *  System.arraycopy(bytes, 0, buffer, offset, bytes.length);
      *  return bytes.length;
      *</pre>
+     *
+     * @param buffer Buffer to append literal (unescaped) String into
+     * @param offset Offset in {@code buffer} to append String at
      * 
      * @return Number of bytes appended, if successful, otherwise -1
      */
     int appendUnquotedUTF8(byte[] buffer, int offset);
 
-
     /**
      * Method that will append unquoted characters of this String into given
      * buffer. Functionally equivalent to:
@@ -123,6 +141,9 @@ public interface SerializableString
      *  System.arraycopy(bytes, 0, buffer, offset, ch.length);
      *  return ch.length;
      *</pre>
+     *
+     * @param buffer Buffer to append literal (unescaped) String into
+     * @param offset Offset in {@code buffer} to append String at
      * 
      * @return Number of characters appended, if successful, otherwise -1
      */
@@ -135,22 +156,50 @@ public interface SerializableString
      */
 
     /**
+     * Method for writing JSON-escaped UTF-8 encoded String value using given
+     * {@link OutputStream}.
+     *
+     * @param out {@link OutputStream} to write String into
+     *
      * @return Number of bytes written
+     *
+     * @throws IOException if underlying stream write fails
      */
     int writeQuotedUTF8(OutputStream out) throws IOException;
 
     /**
+     * Method for writing unescaped UTF-8 encoded String value using given
+     * {@link OutputStream}.
+     *
+     * @param out {@link OutputStream} to write String into
+     *
      * @return Number of bytes written
+     *
+     * @throws IOException if underlying stream write fails
      */
     int writeUnquotedUTF8(OutputStream out) throws IOException;
 
     /**
-     * @return Number of bytes put, if successful, otherwise -1
+     * Method for appending JSON-escaped UTF-8 encoded String value into given
+     * {@link ByteBuffer}, if it fits.
+     *
+     * @param buffer {@link ByteBuffer} to append String into
+     *
+     * @return Number of bytes put, if contents fit, otherwise -1
+     *
+     * @throws IOException if underlying buffer append operation fails
      */
     int putQuotedUTF8(ByteBuffer buffer) throws IOException;
 
     /**
-     * @return Number of bytes put, if successful, otherwise -1
-     */
-    int putUnquotedUTF8(ByteBuffer out) throws IOException;
+     * Method for appending unquoted ('raw') UTF-8 encoded String value into given
+     * {@link ByteBuffer}, if it fits.
+     *
+     * @param buffer {@link ByteBuffer} to append String into
+     *
+     * @return Number of bytes put, if contents fit, otherwise -1
+     *
+     * @throws IOException if underlying buffer append operation fails
+     */
+    int putUnquotedUTF8(ByteBuffer buffer) throws IOException;
 }

src/main/java/com/fasterxml/jackson/core/StreamReadFeature.java

@@ -116,6 +116,8 @@ private StreamReadFeature(JsonParser.Feature mapTo) {
     /**
      * Method that calculates bit set (flags) of all features that
      * are enabled by default.
+     *
+     * @return Bit mask of all features that are enabled by default
      */
     public static int collectDefaults()
     {

src/main/java/com/fasterxml/jackson/core/StreamWriteFeature.java

@@ -135,6 +135,8 @@ private StreamWriteFeature(JsonGenerator.Feature mappedTo) {
     /**
      * Method that calculates bit set (flags) of all features that
      * are enabled by default.
+     *
+     * @return Bit mask of all features that are enabled by default
      */
     public static int collectDefaults()
     {

src/main/java/com/fasterxml/jackson/core/TreeCodec.java

@@ -14,13 +14,18 @@ public abstract class TreeCodec
     public abstract void writeTree(JsonGenerator g, TreeNode tree) throws IOException, JsonProcessingException;
 
     /**
+     * @return Node that represents "missing" node during traversal: something
+     *   referenced but that does not exist in content model
+     * 
      * @since 2.10
      */
     public TreeNode missingNode() {
         return null;
     }
 
     /**
+     * @return Node that represents explict {@code null} value in content
+     * 
      * @since 2.10
      */
     public TreeNode nullNode() {

src/main/java/com/fasterxml/jackson/core/Version.java

@@ -37,9 +37,13 @@ public class Version
     protected final String _snapshotInfo;
 
     /**
-     * @deprecated Use variant that takes group and artifact ids
-     * 
+     * @param major Major version number
+     * @param minor Minor version number
+     * @param patchLevel patch level of version
+     * @param snapshotInfo Optional additional string qualifier
+     *
      * @since 2.1
+     * @deprecated Use variant that takes group and artifact ids
      */
     @Deprecated
     public Version(int major, int minor, int patchLevel, String snapshotInfo)
@@ -61,17 +65,26 @@ public Version(int major, int minor, int patchLevel, String snapshotInfo,
     /**
      * Method returns canonical "not known" version, which is used as version
      * in cases where actual version information is not known (instead of null).
+     *
+     * @return Version instance to use as a placeholder when actual version is not known
+     *   (or not relevant)
      */
     public static Version unknownVersion() { return UNKNOWN_VERSION; }
 
     /**
+     * @return {@code True} if this instance is the one returned by
+     *    call to {@link #unknownVersion()}
+     *
      * @since 2.7 to replace misspelled {@link #isUknownVersion()}
      */
     public boolean isUnknownVersion() { return (this == UNKNOWN_VERSION); }
 
     public boolean isSnapshot() { return (_snapshotInfo != null && _snapshotInfo.length() > 0); }
 
     /**
+     * @return {@code True} if this instance is the one returned by
+     *    call to {@link #unknownVersion()}
+     *
      * @deprecated Since 2.7 use correctly spelled method {@link #isUnknownVersion()}
      */
     @Deprecated

src/main/java/com/fasterxml/jackson/core/util/BufferRecycler.java

@@ -99,7 +99,10 @@ public BufferRecycler() {
     /**
      * Alternate constructor to be used by sub-classes, to allow customization
      * of number of low-level buffers in use.
-     * 
+     *
+     * @param bbCount Number of {@code byte[]} buffers to allocate
+     * @param cbCount Number of {@code char[]} buffers to allocate
+     *
      * @since 2.4
      */
     protected BufferRecycler(int bbCount, int cbCount) {
@@ -115,6 +118,8 @@ protected BufferRecycler(int bbCount, int cbCount) {
 
     /**
      * @param ix One of <code>READ_IO_BUFFER</code> constants.
+     *
+     * @return Buffer allocated (possibly recycled)
      */
     public final byte[] allocByteBuffer(int ix) {
         return allocByteBuffer(ix, 0);