More javadocing

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

@@ -47,6 +47,8 @@ public JsonStringEncoder() { }
     /**
      * Factory method for getting an instance; this is either recycled per-thread instance,
      * or a newly constructed one.
+     *
+     * @return Static stateless encoder instance
      */
     public static JsonStringEncoder getInstance() {
         return instance;
@@ -59,8 +61,12 @@ public static JsonStringEncoder getInstance() {
      */
 
     /**
-     * Method that will quote text contents using JSON standard quoting,
-     * and return results as a character array
+     * Method that will escape text contents using JSON standard escaping,
+     * and return results as a character array.
+     *
+     * @param input Value String to process
+     *
+     * @return JSON-escaped String matching {@code input}
      */
     public char[] quoteAsString(String input)
     {
@@ -131,6 +137,10 @@ public char[] quoteAsString(String input)
     /**
      * Overloaded variant of {@link #quoteAsString(String)}.
      *
+     * @param input Value {@link CharSequence} to process
+     *
+     * @return JSON-escaped String matching {@code input}
+     *
      * @since 2.10
      */
     public char[] quoteAsString(CharSequence input)
@@ -210,6 +220,9 @@ public char[] quoteAsString(CharSequence input)
      * and append results to a supplied {@link StringBuilder}.
      * Use this variant if you have e.g. a {@link StringBuilder} and want to avoid superfluous copying of it.
      *
+     * @param input Value {@link CharSequence} to process
+     * @param output {@link StringBuilder} to append escaped contents to
+     *
      * @since 2.8
      */
     public void quoteAsString(CharSequence input, StringBuilder output)
@@ -247,8 +260,13 @@ public void quoteAsString(CharSequence input, StringBuilder output)
     }
 
     /**
-     * Will quote given JSON String value using standard quoting, encode
-     * results as UTF-8, and return result as a byte array.
+     * Method that will escape text contents using JSON standard escaping,
+     * encode resulting String as UTF-8 bytes
+     * and return results as a  byte array.
+     *
+     * @param text Value {@link String} to process
+     *
+     * @return UTF-8 encoded bytes of JSON-escaped {@code text}
      */
     @SuppressWarnings("resource")
     public byte[] quoteAsUTF8(String text)
@@ -349,8 +367,12 @@ public byte[] quoteAsUTF8(String text)
     }
 
     /**
-     * Will encode given String as UTF-8 (without any quoting), return
-     * resulting byte array.
+     * Will encode given String as UTF-8 (without any escaping) and return
+     * the resulting byte array.
+     *
+     * @param text Value {@link String} to process
+     *
+     * @return UTF-8 encoded bytes of {@code text} (without any escaping)
      */
     @SuppressWarnings("resource")
     public byte[] encodeAsUTF8(String text)
@@ -447,6 +469,10 @@ public byte[] encodeAsUTF8(String text)
     /**
      * Overloaded variant of {@link #encodeAsUTF8(String)}.
      *
+     * @param text Value {@link CharSequence} to process
+     *
+     * @return UTF-8 encoded bytes of {@code text} (without any escaping)
+     *
      * @since 2.11
      */
     @SuppressWarnings("resource")

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

@@ -9,7 +9,8 @@
  * processing during write operations.
  */
 @SuppressWarnings("serial")
-public abstract class OutputDecorator implements java.io.Serializable // since 2.1
+public abstract class OutputDecorator
+    implements java.io.Serializable // since 2.1
 {
     /**
      * Method called by {@link com.fasterxml.jackson.core.JsonFactory} instance when
@@ -21,6 +22,8 @@ public abstract class OutputDecorator implements java.io.Serializable // since 2
      * 
      * @return OutputStream to use; either passed in argument, or something that
      *   calls it
+     *
+     * @throws IOException if construction of decorated {@link OutputStream} fails
      */
     public abstract OutputStream decorate(IOContext ctxt, OutputStream out) throws IOException;
 
@@ -33,6 +36,8 @@ public abstract class OutputDecorator implements java.io.Serializable // since 2
      * @param w Original output writer
      * 
      * @return Writer to use; either passed in argument, or something that calls it
+     *
+     * @throws IOException if construction of decorated {@link Writer} fails
      */
     public abstract Writer decorate(IOContext ctxt, Writer w) throws IOException;
 }

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

@@ -78,6 +78,8 @@ public Writer append(CharSequence csq, int start, int end) {
      * and return result String.
      * Note that the method is not idempotent -- if called second time,
      * will just return an empty String.
+     *
+     * @return String that contains all aggregated content
      */
     public String getAndClear() {
         String result = _buffer.contentsAsString();

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

@@ -351,7 +351,9 @@ public void write(String str, int off, int len)  throws IOException
      */
 
     /**
-     * Method called to calculate UTF codepoint, from a surrogate pair.
+     * Method called to calculate Unicode code-point, from a surrogate pair.
+     *
+     * @param secondPart Second UTF-16 unit of surrogate (first part stored in {@code _surrogate})
      */
     protected int convertSurrogate(int secondPart)
         throws IOException