Minor refactoring... and more javadoc stuff

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/core/io/IOContext.java

@@ -109,9 +109,6 @@ public void setEncoding(JsonEncoding enc) {
         _encoding = enc;
     }
 
-    /**
-     * @since 1.6
-     */
     public IOContext withEncoding(JsonEncoding enc) {
         _encoding = enc;
         return this;
@@ -138,29 +135,54 @@ public TextBuffer constructTextBuffer() {
     }
 
     /**
+     * Method for recycling or allocation byte buffer of "read I/O" type.
      *<p>
      * Note: the method can only be called once during its life cycle.
      * This is to protect against accidental sharing.
+     *
+     * @return Allocated or recycled byte buffer
      */
     public byte[] allocReadIOBuffer() {
         _verifyAlloc(_readIOBuffer);
         return (_readIOBuffer = _bufferRecycler.allocByteBuffer(BufferRecycler.BYTE_READ_IO_BUFFER));
     }
 
     /**
+     * Variant of {@link #allocReadIOBuffer()} that specifies smallest acceptable
+     * buffer size.
+     *
+     * @param minSize Minimum size of the buffer to recycle or allocate
+     *
+     * @return Allocated or recycled byte buffer
+     *
      * @since 2.4
      */
     public byte[] allocReadIOBuffer(int minSize) {
         _verifyAlloc(_readIOBuffer);
         return (_readIOBuffer = _bufferRecycler.allocByteBuffer(BufferRecycler.BYTE_READ_IO_BUFFER, minSize));
     }
-    
+
+    /**
+     * Method for recycling or allocation byte buffer of "write encoding" type.
+     *<p>
+     * Note: the method can only be called once during its life cycle.
+     * This is to protect against accidental sharing.
+     *
+     * @return Allocated or recycled byte buffer
+     */
     public byte[] allocWriteEncodingBuffer() {
         _verifyAlloc(_writeEncodingBuffer);
         return (_writeEncodingBuffer = _bufferRecycler.allocByteBuffer(BufferRecycler.BYTE_WRITE_ENCODING_BUFFER));
     }
 
     /**
+     * Variant of {@link #allocWriteEncodingBuffer()} that specifies smallest acceptable
+     * buffer size.
+     *
+     * @param minSize Minimum size of the buffer to recycle or allocate
+     *
+     * @return Allocated or recycled byte buffer
+     *
      * @since 2.4
      */
     public byte[] allocWriteEncodingBuffer(int minSize) {
@@ -169,14 +191,26 @@ public byte[] allocWriteEncodingBuffer(int minSize) {
     }
 
     /**
-     * @since 2.1
+     * Method for recycling or allocation byte buffer of "base 64 encode/decode" type.
+     *<p>
+     * Note: the method can only be called once during its life cycle.
+     * This is to protect against accidental sharing.
+     *
+     * @return Allocated or recycled byte buffer
      */
     public byte[] allocBase64Buffer() {
         _verifyAlloc(_base64Buffer);
         return (_base64Buffer = _bufferRecycler.allocByteBuffer(BufferRecycler.BYTE_BASE64_CODEC_BUFFER));
     }
 
     /**
+     * Variant of {@link #allocBase64Buffer()} that specifies smallest acceptable
+     * buffer size.
+     *
+     * @param minSize Minimum size of the buffer to recycle or allocate
+     *
+     * @return Allocated or recycled byte buffer
+     *
      * @since 2.9
      */
     public byte[] allocBase64Buffer(int minSize) {
@@ -189,9 +223,7 @@ public char[] allocTokenBuffer() {
         return (_tokenCBuffer = _bufferRecycler.allocCharBuffer(BufferRecycler.CHAR_TOKEN_BUFFER));
     }
 
-    /**
-     * @since 2.4
-     */
+    // @since 2.4
     public char[] allocTokenBuffer(int minSize) {
         _verifyAlloc(_tokenCBuffer);
         return (_tokenCBuffer = _bufferRecycler.allocCharBuffer(BufferRecycler.CHAR_TOKEN_BUFFER, minSize));
@@ -210,12 +242,13 @@ public char[] allocNameCopyBuffer(int minSize) {
     /**
      * Method to call when all the processing buffers can be safely
      * recycled.
+     *
+     * @param buf Buffer instance to release (return for recycling)
      */
     public void releaseReadIOBuffer(byte[] buf) {
         if (buf != null) {
-            /* Let's do sanity checks to ensure once-and-only-once release,
-             * as well as avoiding trying to release buffers not owned
-             */
+            // Let's do sanity checks to ensure once-and-only-once release,
+            // as well as avoiding trying to release buffers not owned
             _verifyRelease(buf, _readIOBuffer);
             _readIOBuffer = null;
             _bufferRecycler.releaseByteBuffer(BufferRecycler.BYTE_READ_IO_BUFFER, buf);
@@ -224,9 +257,8 @@ public void releaseReadIOBuffer(byte[] buf) {
 
     public void releaseWriteEncodingBuffer(byte[] buf) {
         if (buf != null) {
-            /* Let's do sanity checks to ensure once-and-only-once release,
-             * as well as avoiding trying to release buffers not owned
-             */
+            // Let's do sanity checks to ensure once-and-only-once release,
+            // as well as avoiding trying to release buffers not owned
             _verifyRelease(buf, _writeEncodingBuffer);
             _writeEncodingBuffer = null;
             _bufferRecycler.releaseByteBuffer(BufferRecycler.BYTE_WRITE_ENCODING_BUFFER, buf);
@@ -268,9 +300,9 @@ public void releaseNameCopyBuffer(char[] buf) {
     }
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Internal helpers
-    /**********************************************************
+    /**********************************************************************
      */
 
     protected final void _verifyAlloc(Object buffer) {

src/main/java/com/fasterxml/jackson/core/io/JsonEOFException.java

@@ -30,6 +30,8 @@ public JsonEOFException(JsonParser p, JsonToken token, String msg) {
     /**
      * Accessor for possibly available information about token that was being
      * decoded while encountering end of input.
+     *
+     * @return JsonToken that was being decoded while encountering end-of-input
      */
     public JsonToken getTokenBeingDecoded() {
         return _token;

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

@@ -44,19 +44,6 @@ protected VersionUtil() { }
     /**********************************************************************
      */
 
-    /**
-     * Alias of {@link #packageVersionFor(Class)}.
-     *
-     * @param cls Class for which to look version information
-     *
-     * @return Version information discovered if any; 
-     *  {@link Version#unknownVersion()} if none
-     */
-    public static Version versionFor(Class<?> cls)
-    {
-        return packageVersionFor(cls);
-    }
-
     /**
      * Loads version information by introspecting a class named
      * "PackageVersion" in the same package as the given class.
@@ -70,7 +57,7 @@ public static Version versionFor(Class<?> cls)
      * @return Version information discovered if any; 
      *  {@link Version#unknownVersion()} if none
      */
-    public static Version packageVersionFor(Class<?> cls)
+    public static Version versionFor(Class<?> cls)
     {
         Version v = null;
         try {
@@ -88,6 +75,21 @@ public static Version packageVersionFor(Class<?> cls)
         return (v == null) ? Version.unknownVersion() : v;
     }
 
+    /**
+     * Alias of {@link #versionFor(Class)}.
+     *
+     * @param cls Class for which to look version information
+     *
+     * @return Version information discovered if any; 
+     *  {@link Version#unknownVersion()} if none
+     *
+     * @deprecated Since 2.12 simply use {@link #versionFor(Class)} instead
+     */
+    @Deprecated
+    public static Version packageVersionFor(Class<?> cls) {
+        return versionFor(cls);
+    }
+
     /**
      * Will attempt to load the maven version for the given groupId and
      * artifactId.  Maven puts a pom.properties file in