From aa54f0a1b25b84fbdc50af69e71fdd40fcb65be1 Mon Sep 17 00:00:00 2001 From: Tatu Saloranta Date: Mon, 4 Jan 2021 19:25:41 -0800 Subject: [PATCH] javadocs, javadocs --- .../jackson/core/base/GeneratorBase.java | 15 +++++-- .../jackson/core/io/NumberInput.java | 41 +++++++++++++++++-- .../jackson/core/io/NumberOutput.java | 37 +++++++++++++---- .../fasterxml/jackson/core/io/UTF8Writer.java | 4 ++ .../core/json/ByteSourceJsonBootstrapper.java | 17 +++++++- 5 files changed, 98 insertions(+), 16 deletions(-) diff --git a/src/main/java/com/fasterxml/jackson/core/base/GeneratorBase.java b/src/main/java/com/fasterxml/jackson/core/base/GeneratorBase.java index b3bbaca73b..4320a515bb 100644 --- a/src/main/java/com/fasterxml/jackson/core/base/GeneratorBase.java +++ b/src/main/java/com/fasterxml/jackson/core/base/GeneratorBase.java @@ -434,6 +434,9 @@ public void writeTree(TreeNode rootNode) throws IOException { * * @param typeMsg Additional message used for generating exception message * if value output is NOT legal in current generator output state. + * + * @throws IOException if there is either an underlying I/O problem or encoding + * issue at format layer */ protected abstract void _verifyValueWrite(String typeMsg) throws IOException; @@ -441,6 +444,8 @@ public void writeTree(TreeNode rootNode) throws IOException { * Overridable factory method called to instantiate an appropriate {@link PrettyPrinter} * for case of "just use the default one", when {@link #useDefaultPrettyPrinter()} is called. * + * @return Instance of "default" pretty printer to use + * * @since 2.6 */ protected PrettyPrinter _constructDefaultPrettyPrinter() { @@ -451,6 +456,12 @@ protected PrettyPrinter _constructDefaultPrettyPrinter() { * Helper method used to serialize a {@link java.math.BigDecimal} as a String, * for serialization, taking into account configuration settings * + * @param value BigDecimal value to convert to String + * + * @return String representation of {@code value} + * + * @throws IOException if there is a problem serializing value as String + * * @since 2.7.7 */ protected String _asString(BigDecimal value) throws IOException { @@ -473,9 +484,7 @@ protected String _asString(BigDecimal value) throws IOException { /********************************************************** */ - /** - * @since 2.5 - */ + // @since 2.5 protected final int _decodeSurrogate(int surr1, int surr2) throws IOException { // First is known to be valid, but how about the other? diff --git a/src/main/java/com/fasterxml/jackson/core/io/NumberInput.java b/src/main/java/com/fasterxml/jackson/core/io/NumberInput.java index a154d33233..a93236bd72 100644 --- a/src/main/java/com/fasterxml/jackson/core/io/NumberInput.java +++ b/src/main/java/com/fasterxml/jackson/core/io/NumberInput.java @@ -19,11 +19,18 @@ public final class NumberInput final static String MAX_LONG_STR = String.valueOf(Long.MAX_VALUE); /** - * Fast method for parsing integers that are known to fit into + * Fast method for parsing unsigned integers that are known to fit into * regular 32-bit signed int type. This means that length is - * between 1 and 9 digits (inclusive) + * between 1 and 9 digits (inclusive) and there is no sign character. *

- * Note: public to let unit tests call it + * Note: public to let unit tests call it; not meant to be used by any + * code outside this package. + * + * @param ch Buffer that contains integer value to decode + * @param off Offset of the first digit character in buffer + * @param len Length of the number to decode (in characters) + * + * @return Decoded {@code int} value */ public static int parseInt(char[] ch, int off, int len) { @@ -52,7 +59,16 @@ public static int parseInt(char[] ch, int off, int len) /** * Helper method to (more) efficiently parse integer numbers from - * String values. + * String values. Input String must be simple Java integer value. + * No range checks are made to verify that the value fits in 32-bit Java {@code int}: + * caller is expected to only calls this in cases where this can be guaranteed + * (basically: number of digits does not exceed 9) + *

+ * NOTE: semantics differ significantly from {@link #parseInt(char[], int, int)}. + * + * @param s String that contains integer value to decode + * + * @return Decoded {@code int} value */ public static int parseInt(String s) { @@ -115,6 +131,13 @@ public static long parseLong(char[] ch, int off, int len) return val + (long) parseInt(ch, off+len1, 9); } + /** + * Similar to {@link #parseInt(String)} but for {@code long} values. + * + * @param s String that contains {@code long} value to decode + * + * @return Decoded {@code long} value + */ public static long parseLong(String s) { // Ok, now; as the very first thing, let's just optimize case of "fake longs"; @@ -133,8 +156,14 @@ public static long parseLong(String s) * Note that input String must NOT contain leading minus sign (even * if 'negative' is set to true). * + * @param ch Buffer that contains long value to check + * @param off Offset of the first digit character in buffer + * @param len Length of the number to decode (in characters) * @param negative Whether original number had a minus sign (which is * NOT passed to this method) or not + * + * @return {@code True} if specified String representation is within Java + * {@code long} range; {@code false} if not. */ public static boolean inLongRange(char[] ch, int off, int len, boolean negative) @@ -157,8 +186,12 @@ public static boolean inLongRange(char[] ch, int off, int len, * Similar to {@link #inLongRange(char[],int,int,boolean)}, but * with String argument * + * @param s String that contains {@code long} value to check * @param negative Whether original number had a minus sign (which is * NOT passed to this method) or not + * + * @return {@code True} if specified String representation is within Java + * {@code long} range; {@code false} if not. */ public static boolean inLongRange(String s, boolean negative) { diff --git a/src/main/java/com/fasterxml/jackson/core/io/NumberOutput.java b/src/main/java/com/fasterxml/jackson/core/io/NumberOutput.java index 1649b91b29..187a0b4e4c 100644 --- a/src/main/java/com/fasterxml/jackson/core/io/NumberOutput.java +++ b/src/main/java/com/fasterxml/jackson/core/io/NumberOutput.java @@ -21,9 +21,8 @@ public final class NumberOutput private final static int[] TRIPLET_TO_CHARS = new int[1000]; static { - /* Let's fill it with NULLs for ignorable leading digits, - * and digit chars for others - */ + // Let's fill it with NULLs for ignorable leading digits, + // and digit chars for others int fullIx = 0; for (int i1 = 0; i1 < 10; ++i1) { for (int i2 = 0; i2 < 10; ++i2) { @@ -51,7 +50,17 @@ public final class NumberOutput */ /** - * @return Offset within buffer after outputting int + * Method for appending value of given {@code int} value into + * specified {@code char[]}. + *

+ * NOTE: caller must guarantee that the output buffer has enough room + * for String representation of the value. + * + * @param v Value to append to buffer + * @param b Buffer to append value to: caller must guarantee there is enough room + * @param off Offset within output buffer ({@code b}) to append number at + * + * @return Offset within buffer after outputting {@code int} */ public static int outputInt(int v, char[] b, int off) { @@ -152,7 +161,17 @@ public static int outputInt(int v, byte[] b, int off) } /** - * @return Offset within buffer after outputting int + * Method for appending value of given {@code long} value into + * specified {@code char[]}. + *

+ * NOTE: caller must guarantee that the output buffer has enough room + * for String representation of the value. + * + * @param v Value to append to buffer + * @param b Buffer to append value to: caller must guarantee there is enough room + * @param off Offset within output buffer ({@code b}) to append number at + * + * @return Offset within buffer after outputting {@code long} */ public static int outputLong(long v, char[] b, int off) { @@ -258,9 +277,7 @@ public static String toString(double v) { return Double.toString(v); } - /** - * @since 2.6.0 - */ + // @since 2.6 public static String toString(float v) { return Float.toString(v); } @@ -275,6 +292,8 @@ public static String toString(float v) { * Helper method to verify whether given {@code double} value is finite * (regular rational number} or not (NaN or Infinity). * + * @param value {@code double} value to check + * * @return True if number is NOT finite (is Infinity or NaN); false otherwise * * Since 2.10 @@ -288,6 +307,8 @@ public static boolean notFinite(double value) { * Helper method to verify whether given {@code float} value is finite * (regular rational number} or not (NaN or Infinity). * + * @param value {@code float} value to check + * * @return True if number is NOT finite (is Infinity or NaN); false otherwise * * Since 2.10 diff --git a/src/main/java/com/fasterxml/jackson/core/io/UTF8Writer.java b/src/main/java/com/fasterxml/jackson/core/io/UTF8Writer.java index 8feb45d824..0521d25975 100644 --- a/src/main/java/com/fasterxml/jackson/core/io/UTF8Writer.java +++ b/src/main/java/com/fasterxml/jackson/core/io/UTF8Writer.java @@ -354,6 +354,10 @@ public void write(String str, int off, int len) throws IOException * 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}) + * + * @return Decoded Unicode point + * + * @throws IOException If surrogate pair is invalid */ protected int convertSurrogate(int secondPart) throws IOException diff --git a/src/main/java/com/fasterxml/jackson/core/json/ByteSourceJsonBootstrapper.java b/src/main/java/com/fasterxml/jackson/core/json/ByteSourceJsonBootstrapper.java index ce4ce11cd5..2639364c6e 100644 --- a/src/main/java/com/fasterxml/jackson/core/json/ByteSourceJsonBootstrapper.java +++ b/src/main/java/com/fasterxml/jackson/core/json/ByteSourceJsonBootstrapper.java @@ -114,6 +114,10 @@ public ByteSourceJsonBootstrapper(IOContext ctxt, byte[] inputBuffer, int inputS * Method that should be called after constructing an instace. * It will figure out encoding that content uses, to allow * for instantiating a proper scanner object. + * + * @return {@link JsonEncoding} detected, if any; {@code JsonEncoding.UTF8} otherwise + * + * @throws IOException If read from underlying input source fails */ public JsonEncoding detectEncoding() throws IOException { @@ -178,7 +182,12 @@ public JsonEncoding detectEncoding() throws IOException /** * Helper method that may be called to see if given {@link DataInput} * has BOM marker, and if so, to skip it. - * @throws IOException + * + * @param input DataInput to read content from + * + * @return Byte (as unsigned {@code int}) read after possible UTF-8 BOM + * + * @throws IOException If read from underlying input source fails * * @since 2.8 */ @@ -272,6 +281,12 @@ public JsonParser constructParser(int parserFeatures, ObjectCodec codec, * ({@link com.fasterxml.jackson.core.json.ByteSourceJsonBootstrapper}); * supports UTF-8, for example. But it should work, for now, and can * be improved as necessary. + * + * @param acc InputAccessor to use for accessing content to check + * + * @return Strength of match (never {@code null}) + * + * @throws IOException if input access fails due to read problem */ public static MatchStrength hasJSONFormat(InputAccessor acc) throws IOException {