Skip to content

Commit aa54f0a

Browse files
committed
javadocs, javadocs
1 parent e5cbda2 commit aa54f0a

File tree

5 files changed

+98
-16
lines changed

5 files changed

+98
-16
lines changed

src/main/java/com/fasterxml/jackson/core/base/GeneratorBase.java

+12-3
Original file line numberDiff line numberDiff line change
@@ -434,13 +434,18 @@ public void writeTree(TreeNode rootNode) throws IOException {
434434
*
435435
* @param typeMsg Additional message used for generating exception message
436436
* if value output is NOT legal in current generator output state.
437+
*
438+
* @throws IOException if there is either an underlying I/O problem or encoding
439+
* issue at format layer
437440
*/
438441
protected abstract void _verifyValueWrite(String typeMsg) throws IOException;
439442

440443
/**
441444
* Overridable factory method called to instantiate an appropriate {@link PrettyPrinter}
442445
* for case of "just use the default one", when {@link #useDefaultPrettyPrinter()} is called.
443446
*
447+
* @return Instance of "default" pretty printer to use
448+
*
444449
* @since 2.6
445450
*/
446451
protected PrettyPrinter _constructDefaultPrettyPrinter() {
@@ -451,6 +456,12 @@ protected PrettyPrinter _constructDefaultPrettyPrinter() {
451456
* Helper method used to serialize a {@link java.math.BigDecimal} as a String,
452457
* for serialization, taking into account configuration settings
453458
*
459+
* @param value BigDecimal value to convert to String
460+
*
461+
* @return String representation of {@code value}
462+
*
463+
* @throws IOException if there is a problem serializing value as String
464+
*
454465
* @since 2.7.7
455466
*/
456467
protected String _asString(BigDecimal value) throws IOException {
@@ -473,9 +484,7 @@ protected String _asString(BigDecimal value) throws IOException {
473484
/**********************************************************
474485
*/
475486

476-
/**
477-
* @since 2.5
478-
*/
487+
// @since 2.5
479488
protected final int _decodeSurrogate(int surr1, int surr2) throws IOException
480489
{
481490
// First is known to be valid, but how about the other?

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

+37-4
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,18 @@ public final class NumberInput
1919
final static String MAX_LONG_STR = String.valueOf(Long.MAX_VALUE);
2020

2121
/**
22-
* Fast method for parsing integers that are known to fit into
22+
* Fast method for parsing unsigned integers that are known to fit into
2323
* regular 32-bit signed int type. This means that length is
24-
* between 1 and 9 digits (inclusive)
24+
* between 1 and 9 digits (inclusive) and there is no sign character.
2525
*<p>
26-
* Note: public to let unit tests call it
26+
* Note: public to let unit tests call it; not meant to be used by any
27+
* code outside this package.
28+
*
29+
* @param ch Buffer that contains integer value to decode
30+
* @param off Offset of the first digit character in buffer
31+
* @param len Length of the number to decode (in characters)
32+
*
33+
* @return Decoded {@code int} value
2734
*/
2835
public static int parseInt(char[] ch, int off, int len)
2936
{
@@ -52,7 +59,16 @@ public static int parseInt(char[] ch, int off, int len)
5259

5360
/**
5461
* Helper method to (more) efficiently parse integer numbers from
55-
* String values.
62+
* String values. Input String must be simple Java integer value.
63+
* No range checks are made to verify that the value fits in 32-bit Java {@code int}:
64+
* caller is expected to only calls this in cases where this can be guaranteed
65+
* (basically: number of digits does not exceed 9)
66+
*<p>
67+
* NOTE: semantics differ significantly from {@link #parseInt(char[], int, int)}.
68+
*
69+
* @param s String that contains integer value to decode
70+
*
71+
* @return Decoded {@code int} value
5672
*/
5773
public static int parseInt(String s)
5874
{
@@ -115,6 +131,13 @@ public static long parseLong(char[] ch, int off, int len)
115131
return val + (long) parseInt(ch, off+len1, 9);
116132
}
117133

134+
/**
135+
* Similar to {@link #parseInt(String)} but for {@code long} values.
136+
*
137+
* @param s String that contains {@code long} value to decode
138+
*
139+
* @return Decoded {@code long} value
140+
*/
118141
public static long parseLong(String s)
119142
{
120143
// 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)
133156
* Note that input String must NOT contain leading minus sign (even
134157
* if 'negative' is set to true).
135158
*
159+
* @param ch Buffer that contains long value to check
160+
* @param off Offset of the first digit character in buffer
161+
* @param len Length of the number to decode (in characters)
136162
* @param negative Whether original number had a minus sign (which is
137163
* NOT passed to this method) or not
164+
*
165+
* @return {@code True} if specified String representation is within Java
166+
* {@code long} range; {@code false} if not.
138167
*/
139168
public static boolean inLongRange(char[] ch, int off, int len,
140169
boolean negative)
@@ -157,8 +186,12 @@ public static boolean inLongRange(char[] ch, int off, int len,
157186
* Similar to {@link #inLongRange(char[],int,int,boolean)}, but
158187
* with String argument
159188
*
189+
* @param s String that contains {@code long} value to check
160190
* @param negative Whether original number had a minus sign (which is
161191
* NOT passed to this method) or not
192+
*
193+
* @return {@code True} if specified String representation is within Java
194+
* {@code long} range; {@code false} if not.
162195
*/
163196
public static boolean inLongRange(String s, boolean negative)
164197
{

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

+29-8
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,8 @@ public final class NumberOutput
2121
private final static int[] TRIPLET_TO_CHARS = new int[1000];
2222

2323
static {
24-
/* Let's fill it with NULLs for ignorable leading digits,
25-
* and digit chars for others
26-
*/
24+
// Let's fill it with NULLs for ignorable leading digits,
25+
// and digit chars for others
2726
int fullIx = 0;
2827
for (int i1 = 0; i1 < 10; ++i1) {
2928
for (int i2 = 0; i2 < 10; ++i2) {
@@ -51,7 +50,17 @@ public final class NumberOutput
5150
*/
5251

5352
/**
54-
* @return Offset within buffer after outputting int
53+
* Method for appending value of given {@code int} value into
54+
* specified {@code char[]}.
55+
*<p>
56+
* NOTE: caller must guarantee that the output buffer has enough room
57+
* for String representation of the value.
58+
*
59+
* @param v Value to append to buffer
60+
* @param b Buffer to append value to: caller must guarantee there is enough room
61+
* @param off Offset within output buffer ({@code b}) to append number at
62+
*
63+
* @return Offset within buffer after outputting {@code int}
5564
*/
5665
public static int outputInt(int v, char[] b, int off)
5766
{
@@ -152,7 +161,17 @@ public static int outputInt(int v, byte[] b, int off)
152161
}
153162

154163
/**
155-
* @return Offset within buffer after outputting int
164+
* Method for appending value of given {@code long} value into
165+
* specified {@code char[]}.
166+
*<p>
167+
* NOTE: caller must guarantee that the output buffer has enough room
168+
* for String representation of the value.
169+
*
170+
* @param v Value to append to buffer
171+
* @param b Buffer to append value to: caller must guarantee there is enough room
172+
* @param off Offset within output buffer ({@code b}) to append number at
173+
*
174+
* @return Offset within buffer after outputting {@code long}
156175
*/
157176
public static int outputLong(long v, char[] b, int off)
158177
{
@@ -258,9 +277,7 @@ public static String toString(double v) {
258277
return Double.toString(v);
259278
}
260279

261-
/**
262-
* @since 2.6.0
263-
*/
280+
// @since 2.6
264281
public static String toString(float v) {
265282
return Float.toString(v);
266283
}
@@ -275,6 +292,8 @@ public static String toString(float v) {
275292
* Helper method to verify whether given {@code double} value is finite
276293
* (regular rational number} or not (NaN or Infinity).
277294
*
295+
* @param value {@code double} value to check
296+
*
278297
* @return True if number is NOT finite (is Infinity or NaN); false otherwise
279298
*
280299
* Since 2.10
@@ -288,6 +307,8 @@ public static boolean notFinite(double value) {
288307
* Helper method to verify whether given {@code float} value is finite
289308
* (regular rational number} or not (NaN or Infinity).
290309
*
310+
* @param value {@code float} value to check
311+
*
291312
* @return True if number is NOT finite (is Infinity or NaN); false otherwise
292313
*
293314
* Since 2.10

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

+4
Original file line numberDiff line numberDiff line change
@@ -354,6 +354,10 @@ public void write(String str, int off, int len) throws IOException
354354
* Method called to calculate Unicode code-point, from a surrogate pair.
355355
*
356356
* @param secondPart Second UTF-16 unit of surrogate (first part stored in {@code _surrogate})
357+
*
358+
* @return Decoded Unicode point
359+
*
360+
* @throws IOException If surrogate pair is invalid
357361
*/
358362
protected int convertSurrogate(int secondPart)
359363
throws IOException

src/main/java/com/fasterxml/jackson/core/json/ByteSourceJsonBootstrapper.java

+16-1
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,10 @@ public ByteSourceJsonBootstrapper(IOContext ctxt, byte[] inputBuffer, int inputS
114114
* Method that should be called after constructing an instace.
115115
* It will figure out encoding that content uses, to allow
116116
* for instantiating a proper scanner object.
117+
*
118+
* @return {@link JsonEncoding} detected, if any; {@code JsonEncoding.UTF8} otherwise
119+
*
120+
* @throws IOException If read from underlying input source fails
117121
*/
118122
public JsonEncoding detectEncoding() throws IOException
119123
{
@@ -178,7 +182,12 @@ public JsonEncoding detectEncoding() throws IOException
178182
/**
179183
* Helper method that may be called to see if given {@link DataInput}
180184
* has BOM marker, and if so, to skip it.
181-
* @throws IOException
185+
*
186+
* @param input DataInput to read content from
187+
*
188+
* @return Byte (as unsigned {@code int}) read after possible UTF-8 BOM
189+
*
190+
* @throws IOException If read from underlying input source fails
182191
*
183192
* @since 2.8
184193
*/
@@ -272,6 +281,12 @@ public JsonParser constructParser(int parserFeatures, ObjectCodec codec,
272281
* ({@link com.fasterxml.jackson.core.json.ByteSourceJsonBootstrapper});
273282
* supports UTF-8, for example. But it should work, for now, and can
274283
* be improved as necessary.
284+
*
285+
* @param acc InputAccessor to use for accessing content to check
286+
*
287+
* @return Strength of match (never {@code null})
288+
*
289+
* @throws IOException if input access fails due to read problem
275290
*/
276291
public static MatchStrength hasJSONFormat(InputAccessor acc) throws IOException
277292
{

0 commit comments

Comments
 (0)