Skip to content

Commit a40a7f7

Browse files
committed
yet more javadoc fixes
1 parent 01d1e88 commit a40a7f7

16 files changed

+196
-39
lines changed

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

+53-7
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,15 @@ public interface PrettyPrinter
5151
* Method called after a root-level value has been completely
5252
* output, and before another value is to be output.
5353
*<p>
54-
* Default
55-
* handling (without pretty-printing) will output a space, to
54+
* Default handling (without pretty-printing) will output a space, to
5655
* allow values to be parsed correctly. Pretty-printer is
5756
* to output some other suitable and nice-looking separator
5857
* (tab(s), space(s), linefeed(s) or any combination thereof).
58+
*
59+
* @param gen Generator used for output
60+
*
61+
* @throws IOException if there is either an underlying I/O problem or encoding
62+
* issue at format layer
5963
*/
6064
void writeRootValueSeparator(JsonGenerator gen) throws IOException;
6165

@@ -70,6 +74,11 @@ public interface PrettyPrinter
7074
* Pretty-printer is
7175
* to output a curly bracket as well, but can surround that
7276
* with other (white-space) decoration.
77+
*
78+
* @param gen Generator used for output
79+
*
80+
* @throws IOException if there is either an underlying I/O problem or encoding
81+
* issue at format layer
7382
*/
7483
void writeStartObject(JsonGenerator gen) throws IOException;
7584

@@ -83,19 +92,28 @@ public interface PrettyPrinter
8392
* to output a curly bracket as well, but can surround that
8493
* with other (white-space) decoration.
8594
*
86-
* @param nrOfEntries Number of direct members of the array that
95+
* @param gen Generator used for output
96+
* @param nrOfEntries Number of direct members of the Object that
8797
* have been output
98+
*
99+
* @throws IOException if there is either an underlying I/O problem or encoding
100+
* issue at format layer
88101
*/
89102
void writeEndObject(JsonGenerator gen, int nrOfEntries) throws IOException;
90103

91104
/**
92-
* Method called after an object entry (field:value) has been completely
105+
* Method called after an Object entry (field:value) has been completely
93106
* output, and before another value is to be output.
94107
*<p>
95108
* Default handling (without pretty-printing) will output a single
96109
* comma to separate the two. Pretty-printer is
97110
* to output a comma as well, but can surround that with other
98111
* (white-space) decoration.
112+
*
113+
* @param gen Generator used for output
114+
*
115+
* @throws IOException if there is either an underlying I/O problem or encoding
116+
* issue at format layer
99117
*/
100118
void writeObjectEntrySeparator(JsonGenerator gen) throws IOException;
101119

@@ -107,6 +125,11 @@ public interface PrettyPrinter
107125
* colon to separate the two. Pretty-printer is
108126
* to output a colon as well, but can surround that with other
109127
* (white-space) decoration.
128+
*
129+
* @param gen Generator used for output
130+
*
131+
* @throws IOException if there is either an underlying I/O problem or encoding
132+
* issue at format layer
110133
*/
111134
void writeObjectFieldValueSeparator(JsonGenerator gen) throws IOException;
112135

@@ -121,6 +144,11 @@ public interface PrettyPrinter
121144
* Pretty-printer is
122145
* to output a bracket as well, but can surround that
123146
* with other (white-space) decoration.
147+
*
148+
* @param gen Generator used for output
149+
*
150+
* @throws IOException if there is either an underlying I/O problem or encoding
151+
* issue at format layer
124152
*/
125153
void writeStartArray(JsonGenerator gen) throws IOException;
126154

@@ -134,8 +162,12 @@ public interface PrettyPrinter
134162
* to output a bracket as well, but can surround that
135163
* with other (white-space) decoration.
136164
*
165+
* @param gen Generator used for output
137166
* @param nrOfValues Number of direct members of the array that
138167
* have been output
168+
*
169+
* @throws IOException if there is either an underlying I/O problem or encoding
170+
* issue at format layer
139171
*/
140172
void writeEndArray(JsonGenerator gen, int nrOfValues) throws IOException;
141173

@@ -147,14 +179,18 @@ public interface PrettyPrinter
147179
* comma to separate the two. Pretty-printer is
148180
* to output a comma as well, but can surround that with other
149181
* (white-space) decoration.
182+
*
183+
* @param gen Generator used for output
184+
*
185+
* @throws IOException if there is either an underlying I/O problem or encoding
186+
* issue at format layer
150187
*/
151188
void writeArrayValueSeparator(JsonGenerator gen) throws IOException;
152189

153190
/*
154191
/**********************************************************
155-
/* Then events that by default do not produce any output
156-
/* but that are often overridden to add white space
157-
/* in pretty-printing mode
192+
/* Then events that by default do not produce any output but that are
193+
/* often overridden to add white space in pretty-printing mode
158194
/**********************************************************
159195
*/
160196

@@ -165,6 +201,11 @@ public interface PrettyPrinter
165201
*<p>
166202
* Default handling does not output anything, but pretty-printer
167203
* is free to add any white space decoration.
204+
*
205+
* @param gen Generator used for output
206+
*
207+
* @throws IOException if there is either an underlying I/O problem or encoding
208+
* issue at format layer
168209
*/
169210
void beforeArrayValues(JsonGenerator gen) throws IOException;
170211

@@ -176,6 +217,11 @@ public interface PrettyPrinter
176217
*<p>
177218
* Default handling does not output anything, but pretty-printer
178219
* is free to add any white space decoration.
220+
*
221+
* @param gen Generator used for output
222+
*
223+
* @throws IOException if there is either an underlying I/O problem or encoding
224+
* issue at format layer
179225
*/
180226
void beforeObjectEntries(JsonGenerator gen) throws IOException;
181227
}

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

+55-6
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ public interface SerializableString
2626
/**
2727
* Returns unquoted String that this object represents (and offers
2828
* serialized forms for)
29+
*
30+
* @return Unquoted String
2931
*/
3032
String getValue();
3133

@@ -35,6 +37,8 @@ public interface SerializableString
3537
*<pre>
3638
* getValue().length();
3739
*</pre>
40+
*
41+
* @return Length of the String in characters
3842
*/
3943
int charLength();
4044

@@ -47,6 +51,8 @@ public interface SerializableString
4751
/**
4852
* Returns JSON quoted form of the String, as character array.
4953
* Result can be embedded as-is in textual JSON as property name or JSON String.
54+
*
55+
* @return JSON quoted form of the String as {@code char[]}
5056
*/
5157
char[] asQuotedChars();
5258

@@ -56,6 +62,8 @@ public interface SerializableString
5662
*<pre>
5763
* getValue().getBytes("UTF-8");
5864
*</pre>
65+
*
66+
* @return UTF-8 encoded version of String, without any escaping
5967
*/
6068
byte[] asUnquotedUTF8();
6169

@@ -65,6 +73,8 @@ public interface SerializableString
6573
*<pre>
6674
* new String(asQuotedChars()).getBytes("UTF-8");
6775
*</pre>
76+
*
77+
* @return UTF-8 encoded version of JSON-escaped String
6878
*/
6979
byte[] asQuotedUTF8();
7080

@@ -83,7 +93,10 @@ public interface SerializableString
8393
* System.arraycopy(bytes, 0, buffer, offset, bytes.length);
8494
* return bytes.length;
8595
*</pre>
86-
*
96+
*
97+
* @param buffer Buffer to append JSON-escaped String into
98+
* @param offset Offset in {@code buffer} to append String at
99+
*
87100
* @return Number of bytes appended, if successful, otherwise -1
88101
*/
89102
int appendQuotedUTF8(byte[] buffer, int offset);
@@ -96,6 +109,9 @@ public interface SerializableString
96109
* System.arraycopy(ch, 0, buffer, offset, ch.length);
97110
* return ch.length;
98111
*</pre>
112+
*
113+
* @param buffer Buffer to append JSON-escaped String into
114+
* @param offset Offset in {@code buffer} to append String at
99115
*
100116
* @return Number of characters appended, if successful, otherwise -1
101117
*/
@@ -109,12 +125,14 @@ public interface SerializableString
109125
* System.arraycopy(bytes, 0, buffer, offset, bytes.length);
110126
* return bytes.length;
111127
*</pre>
128+
*
129+
* @param buffer Buffer to append literal (unescaped) String into
130+
* @param offset Offset in {@code buffer} to append String at
112131
*
113132
* @return Number of bytes appended, if successful, otherwise -1
114133
*/
115134
int appendUnquotedUTF8(byte[] buffer, int offset);
116135

117-
118136
/**
119137
* Method that will append unquoted characters of this String into given
120138
* buffer. Functionally equivalent to:
@@ -123,6 +141,9 @@ public interface SerializableString
123141
* System.arraycopy(bytes, 0, buffer, offset, ch.length);
124142
* return ch.length;
125143
*</pre>
144+
*
145+
* @param buffer Buffer to append literal (unescaped) String into
146+
* @param offset Offset in {@code buffer} to append String at
126147
*
127148
* @return Number of characters appended, if successful, otherwise -1
128149
*/
@@ -135,22 +156,50 @@ public interface SerializableString
135156
*/
136157

137158
/**
159+
* Method for writing JSON-escaped UTF-8 encoded String value using given
160+
* {@link OutputStream}.
161+
*
162+
* @param out {@link OutputStream} to write String into
163+
*
138164
* @return Number of bytes written
165+
*
166+
* @throws IOException if underlying stream write fails
139167
*/
140168
int writeQuotedUTF8(OutputStream out) throws IOException;
141169

142170
/**
171+
* Method for writing unescaped UTF-8 encoded String value using given
172+
* {@link OutputStream}.
173+
*
174+
* @param out {@link OutputStream} to write String into
175+
*
143176
* @return Number of bytes written
177+
*
178+
* @throws IOException if underlying stream write fails
144179
*/
145180
int writeUnquotedUTF8(OutputStream out) throws IOException;
146181

147182
/**
148-
* @return Number of bytes put, if successful, otherwise -1
183+
* Method for appending JSON-escaped UTF-8 encoded String value into given
184+
* {@link ByteBuffer}, if it fits.
185+
*
186+
* @param buffer {@link ByteBuffer} to append String into
187+
*
188+
* @return Number of bytes put, if contents fit, otherwise -1
189+
*
190+
* @throws IOException if underlying buffer append operation fails
149191
*/
150192
int putQuotedUTF8(ByteBuffer buffer) throws IOException;
151193

152194
/**
153-
* @return Number of bytes put, if successful, otherwise -1
154-
*/
155-
int putUnquotedUTF8(ByteBuffer out) throws IOException;
195+
* Method for appending unquoted ('raw') UTF-8 encoded String value into given
196+
* {@link ByteBuffer}, if it fits.
197+
*
198+
* @param buffer {@link ByteBuffer} to append String into
199+
*
200+
* @return Number of bytes put, if contents fit, otherwise -1
201+
*
202+
* @throws IOException if underlying buffer append operation fails
203+
*/
204+
int putUnquotedUTF8(ByteBuffer buffer) throws IOException;
156205
}

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

+2
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,8 @@ private StreamReadFeature(JsonParser.Feature mapTo) {
116116
/**
117117
* Method that calculates bit set (flags) of all features that
118118
* are enabled by default.
119+
*
120+
* @return Bit mask of all features that are enabled by default
119121
*/
120122
public static int collectDefaults()
121123
{

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

+2
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,8 @@ private StreamWriteFeature(JsonGenerator.Feature mappedTo) {
135135
/**
136136
* Method that calculates bit set (flags) of all features that
137137
* are enabled by default.
138+
*
139+
* @return Bit mask of all features that are enabled by default
138140
*/
139141
public static int collectDefaults()
140142
{

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

+5
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,18 @@ public abstract class TreeCodec
1414
public abstract void writeTree(JsonGenerator g, TreeNode tree) throws IOException, JsonProcessingException;
1515

1616
/**
17+
* @return Node that represents "missing" node during traversal: something
18+
* referenced but that does not exist in content model
19+
*
1720
* @since 2.10
1821
*/
1922
public TreeNode missingNode() {
2023
return null;
2124
}
2225

2326
/**
27+
* @return Node that represents explict {@code null} value in content
28+
*
2429
* @since 2.10
2530
*/
2631
public TreeNode nullNode() {

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

+15-2
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,13 @@ public class Version
3737
protected final String _snapshotInfo;
3838

3939
/**
40-
* @deprecated Use variant that takes group and artifact ids
41-
*
40+
* @param major Major version number
41+
* @param minor Minor version number
42+
* @param patchLevel patch level of version
43+
* @param snapshotInfo Optional additional string qualifier
44+
*
4245
* @since 2.1
46+
* @deprecated Use variant that takes group and artifact ids
4347
*/
4448
@Deprecated
4549
public Version(int major, int minor, int patchLevel, String snapshotInfo)
@@ -61,17 +65,26 @@ public Version(int major, int minor, int patchLevel, String snapshotInfo,
6165
/**
6266
* Method returns canonical "not known" version, which is used as version
6367
* in cases where actual version information is not known (instead of null).
68+
*
69+
* @return Version instance to use as a placeholder when actual version is not known
70+
* (or not relevant)
6471
*/
6572
public static Version unknownVersion() { return UNKNOWN_VERSION; }
6673

6774
/**
75+
* @return {@code True} if this instance is the one returned by
76+
* call to {@link #unknownVersion()}
77+
*
6878
* @since 2.7 to replace misspelled {@link #isUknownVersion()}
6979
*/
7080
public boolean isUnknownVersion() { return (this == UNKNOWN_VERSION); }
7181

7282
public boolean isSnapshot() { return (_snapshotInfo != null && _snapshotInfo.length() > 0); }
7383

7484
/**
85+
* @return {@code True} if this instance is the one returned by
86+
* call to {@link #unknownVersion()}
87+
*
7588
* @deprecated Since 2.7 use correctly spelled method {@link #isUnknownVersion()}
7689
*/
7790
@Deprecated

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

+6-1
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,10 @@ public BufferRecycler() {
9999
/**
100100
* Alternate constructor to be used by sub-classes, to allow customization
101101
* of number of low-level buffers in use.
102-
*
102+
*
103+
* @param bbCount Number of {@code byte[]} buffers to allocate
104+
* @param cbCount Number of {@code char[]} buffers to allocate
105+
*
103106
* @since 2.4
104107
*/
105108
protected BufferRecycler(int bbCount, int cbCount) {
@@ -115,6 +118,8 @@ protected BufferRecycler(int bbCount, int cbCount) {
115118

116119
/**
117120
* @param ix One of <code>READ_IO_BUFFER</code> constants.
121+
*
122+
* @return Buffer allocated (possibly recycled)
118123
*/
119124
public final byte[] allocByteBuffer(int ix) {
120125
return allocByteBuffer(ix, 0);

0 commit comments

Comments
 (0)