Skip to content

Commit 6f5cbab

Browse files
dmaccormackdmaccormack
committed
doc: Update Javadocs and comments
1 parent f5b78c9 commit 6f5cbab

File tree

4 files changed

+66
-28
lines changed

4 files changed

+66
-28
lines changed

‎module/jsonurl-core/src/main/java/org/jsonurl/JsonUrlOption.java‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,6 @@ public enum JsonUrlOption {
4444
* The implied-string-literals option.
4545
* If this option is enabled then all literals are assumed to be strings.
4646
* @see #enableImpliedStringLiterals(Set)
47-
* @see <a href="https://github.com/jsonurl/specification/#292-implied-objects"
48-
* >JSON&#x2192;URL specification, section 2.9.2</a>
4947
*/
5048
IMPLIED_STRING_LITERALS,
5149

‎module/jsonurl-core/src/main/java/org/jsonurl/stream/JsonUrlIterator.java‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,16 @@
4949
* {@code VALUE_STRING} is returned.</td>
5050
* </tr>
5151
*
52+
* <tr>
53+
* <td>{@link org.jsonurl.JsonUrlOption#IMPLIED_STRING_LITERALS IMPLIED_STRING_LITERALS}
54+
* + {@link org.jsonurl.JsonUrlOption#AQF AQF}</td>
55+
* <td>When both flags are present then the grammar allows for either
56+
* {@link JsonUrlEvent#VALUE_STRING VALUE_STRING} or
57+
* {@link JsonUrlEvent#VALUE_EMPTY_LITERAL VALUE_EMPTY_LITERAL}.
58+
* In this case the implied string option takes precedence and
59+
* {@code VALUE_STRING} is returned.</td>
60+
* </tr>
61+
*
5262
* </table>
5363
*
5464
* @author jsonurl.org

‎module/jsonurl-core/src/main/java/org/jsonurl/text/NumberBuilder.java‎

Lines changed: 36 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@
5959
* {@link #reset()} method.
6060
* <pre>
6161
* NumberBuilder nb = new NumberBuilder();
62-
* if (!nb.{@link #parse(CharSequence, int, int) parse("1.234")}) {
62+
* if (!nb.{@link #parse(CharSequence) parse("1.234")}) {
6363
* // handle the error
6464
* }
6565
*
@@ -84,9 +84,12 @@
8484
* allocating an instance. They're useful if you want test validity but
8585
* don't need access to the parsed value.
8686
* <pre>
87-
* boolean b = NumberBuilder.{@link #isNumber() isNumber("1234")};
88-
* boolean b = NumberBuilder.{@link #isNumber() isNumber("abcd")};
89-
* boolean b = NumberBuilder.{@link #isNonFractional() isInteger("1234.5")};
87+
* boolean b = NumberBuilder.{@link #isNumber(CharSequence)
88+
* isNumber("1234")};
89+
* boolean b = NumberBuilder.{@link #isNumber(CharSequence)
90+
* isNumber("abcd")};
91+
* boolean b = NumberBuilder.{@link #isNonFractional(CharSequence)
92+
* isNonFractional("1234.5")};
9093
* </pre>
9194
*
9295
* @author jsonurl.org
@@ -216,7 +219,7 @@ public class NumberBuilder implements NumberText { // NOPMD
216219
* Create a new NumberBuilder.
217220
*
218221
* <p>This NumberBuilder will not have any text. You'll need to call
219-
* {@link #parse(CharSequence, int, int)}.
222+
* {@link #parse(CharSequence)}.
220223
*/
221224
public NumberBuilder() {
222225
mcp = null;
@@ -226,7 +229,7 @@ public NumberBuilder() {
226229
* Create a new NumberBuilder.
227230
*
228231
* <p>This NumberBuilder will not have any text. You'll need to call
229-
* {@link #parse(CharSequence, int, int)}.
232+
* {@link #parse(CharSequence)}.
230233
*/
231234
public NumberBuilder(BigMathProvider mcp) {
232235
this.mcp = mcp;
@@ -323,7 +326,7 @@ public NumberBuilder(NumberText text, BigMathProvider mcp) {
323326

324327
/**
325328
* Reset the instance for reuse. You may reliably call
326-
* {@link #parse(CharSequence, int, int)} again after calling this
329+
* {@link #parse(CharSequence, int, int, Set)} again after calling this
327330
* method.
328331
*/
329332
public NumberBuilder reset() {
@@ -333,8 +336,8 @@ public NumberBuilder reset() {
333336

334337
/**
335338
* Reset internal state.
336-
* @param leaveText if true then do not touch {@link #start}, {@link #stop},
337-
* or {@link #text}.
339+
* @param leaveText if true then do not touch
340+
* {@link #start}, {@link #stop}, or {@link #text}.
338341
*/
339342
private void reset(boolean leaveText) {
340343
if (!leaveText) {
@@ -434,8 +437,8 @@ private static NumberText.Exponent getExponentType(//NOPMD
434437

435438
/**
436439
* Parse the given character sequence.
437-
* This is a convenience for {@link #parse(CharSequence, int, int)
438-
* parse(text, 0, text.length)}.
440+
* This is a convenience for {@link #parse(CharSequence, int, int, Set)
441+
* parse(text, 0, text.length, null)}.
439442
*
440443
* @param text a valid CharSequence
441444
*/
@@ -445,8 +448,8 @@ public boolean parse(CharSequence text) {
445448

446449
/**
447450
* Parse the given character sequence.
448-
* This is a convenience for {@link #parse(CharSequence, int, int)
449-
* parse(text, 0, text.length)}.
451+
* This is a convenience for {@link #parse(CharSequence, int, int, Set)
452+
* parse(text, 0, text.length, options)}.
450453
*
451454
* @param text a valid CharSequence
452455
*/
@@ -545,8 +548,9 @@ public boolean parse(//NOPMD
545548
/**
546549
* Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
547550
*
548-
* <p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)
549-
* isNumber(s, 0, s.length(), false)}.
551+
* <p>Convenience for {@link
552+
* #isNumber(CharSequence, int, int, boolean, Set)
553+
* isNumber(s, 0, s.length(), false, null)}.
550554
*/
551555
public static boolean isNumber(CharSequence text) {
552556
return isNumber(text, 0, text.length(), false, null);
@@ -555,8 +559,9 @@ public static boolean isNumber(CharSequence text) {
555559
/**
556560
* Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
557561
*
558-
* <p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)
559-
* isNumber(s, 0, s.length(), isInteger)}.
562+
* <p>Convenience for {@link
563+
* #isNumber(CharSequence, int, int, boolean, Set)
564+
* isNumber(s, 0, s.length(), isInteger, null)}.
560565
*/
561566
public static boolean isNumber(CharSequence text, boolean isNonFractional) {
562567
return isNumber(text, 0, text.length(), isNonFractional, null);
@@ -565,8 +570,9 @@ public static boolean isNumber(CharSequence text, boolean isNonFractional) {
565570
/**
566571
* Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
567572
*
568-
* <p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)}
569-
* isNumber(s, 0, stop, false)}.
573+
* <p>Convenience for {@link
574+
* #isNumber(CharSequence, int, int, boolean, Set)
575+
* isNumber(s, 0, stop, false, null)}.
570576
* @param text a valid CharSequence
571577
* @param start an index
572578
* @param stop an index
@@ -582,8 +588,9 @@ public static boolean isNumber(
582588
/**
583589
* Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
584590
*
585-
* <p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)}
586-
* isNumber(s, 0, stop, false)}.
591+
* <p>Convenience for {@link
592+
* #isNumber(CharSequence, int, int, boolean, Set)
593+
* isNumber(s, 0, stop, false, options)}.
587594
* @param text a valid CharSequence
588595
* @param start an index
589596
* @param stop an index
@@ -684,7 +691,8 @@ public static boolean isNumber(//NOPMD
684691
/**
685692
* Determine if this text represents a valid JSON&#x2192;URL number literal.
686693
*
687-
* <p>This is the result of calling {@link #parse(CharSequence, int, int)}.
694+
* <p>This is the result of calling
695+
* {@link #parse(CharSequence, int, int, Set)}.
688696
* @return true if this text represents is a JSON&#x2192;URL number literal
689697
*/
690698
public boolean isNumber() {
@@ -694,8 +702,9 @@ public boolean isNumber() {
694702
/**
695703
* Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
696704
*
697-
*<p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)
698-
* isNumber(s, 0, s.length(), true)}.
705+
*<p>Convenience for {@link
706+
*#isNumber(CharSequence, int, int, boolean, Set)
707+
* isNumber(s, 0, s.length(), true, null)}.
699708
*/
700709
public static boolean isNonFractional(CharSequence text) {
701710
return isNumber(text, 0, text.length(), true, null);
@@ -704,8 +713,9 @@ public static boolean isNonFractional(CharSequence text) {
704713
/**
705714
* Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
706715
*
707-
*<p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)
708-
* isNumber(s, start, stop, true)}.
716+
*<p>Convenience for {@link
717+
*#isNumber(CharSequence, int, int, boolean, Set)
718+
* isNumber(s, start, stop, true, null)}.
709719
*/
710720
public static boolean isNonFractional(
711721
CharSequence text,

‎module/jsonurl-factory/src/main/java/org/jsonurl/factory/Parser.java‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,13 +96,15 @@ interface TransparentBuilder<
9696

9797
/**
9898
* Parse the given JSON&#x2192;URL text.
99+
* @see #parseObject(CharSequence, int, int, Object, MissingValueProvider)
99100
*/
100101
default J parseObject(CharSequence text) {
101102
return parseObject(text, 0, text.length(), null);
102103
}
103104

104105
/**
105106
* Parse the given JSON&#x2192;URL text.
107+
* @see #parseObject(CharSequence, int, int, Object, MissingValueProvider)
106108
*/
107109
default J parseObject(
108110
CharSequence text,
@@ -113,6 +115,7 @@ default J parseObject(
113115

114116
/**
115117
* Parse the given JSON&#x2192;URL text.
118+
* @see #parseObject(CharSequence, int, int, Object, MissingValueProvider)
116119
*/
117120
default J parseObject(
118121
CharSequence text,
@@ -122,6 +125,7 @@ default J parseObject(
122125

123126
/**
124127
* Parse the given JSON&#x2192;URL text.
128+
* @see #parseObject(CharSequence, int, int, Object, MissingValueProvider)
125129
*/
126130
default J parseObject(
127131
CharSequence text,
@@ -132,6 +136,7 @@ default J parseObject(
132136

133137
/**
134138
* Parse the given JSON&#x2192;URL text.
139+
* @see #parseObject(CharSequence, int, int, Object, MissingValueProvider)
135140
*/
136141
default J parseObject(
137142
CharSequence text,
@@ -148,6 +153,7 @@ default J parseObject(
148153
* @param length number of characters in {@code text} to parse
149154
* @param impliedObject a valid factory object or {@code null}
150155
* @param mvp a valid MissingValueProvider or {@code null}
156+
* @see #parseObject(JsonUrlIterator, Object, MissingValueProvider)
151157
*/
152158
default J parseObject(
153159
CharSequence text,
@@ -173,6 +179,7 @@ default J parseObject(
173179
* @param iter a valid CharIterator
174180
* @param impliedObject a valid factory object or {@code null}
175181
* @param mvp a valid MissingValueProvider or {@code null}
182+
* @see #parseObject(JsonUrlIterator, Object, MissingValueProvider)
176183
*/
177184
default J parseObject(
178185
CharIterator iter,
@@ -190,6 +197,10 @@ default J parseObject(
190197
* @param iter a valid JsonUrlIterator
191198
* @param impliedObject a valid factory object or {@code null}
192199
* @param mvp a valid MissingValueProvider or {@code null}
200+
* @see <a href="https://github.com/jsonurl/specification/#292-implied-objects"
201+
* >JSON&#x2192;URL specification, section 2.9.2</a>
202+
* @see <a href="https://github.com/jsonurl/specification/#294-implied-object-missing-values"
203+
* >JSON&#x2192;URL specification, section 2.9.4</a>
193204
*/
194205
J parseObject(
195206
JsonUrlIterator iter,
@@ -198,13 +209,15 @@ J parseObject(
198209

199210
/**
200211
* Parse the given JSON&#x2192;URL text.
212+
* @see #parseArray(CharSequence, int, int, Object, MissingValueProvider)
201213
*/
202214
default A parseArray(CharSequence text) {
203215
return parseArray(text, 0, text.length(), null);
204216
}
205217

206218
/**
207219
* Parse the given JSON&#x2192;URL text.
220+
* @see #parseArray(CharSequence, int, int, Object, MissingValueProvider)
208221
*/
209222
default A parseArray(
210223
CharSequence text,
@@ -215,6 +228,7 @@ default A parseArray(
215228

216229
/**
217230
* Parse the given JSON&#x2192;URL text.
231+
* @see #parseArray(CharSequence, int, int, Object, MissingValueProvider)
218232
*/
219233
default A parseArray(
220234
CharSequence text,
@@ -224,6 +238,7 @@ default A parseArray(
224238

225239
/**
226240
* Parse the given JSON&#x2192;URL text.
241+
* @see #parseArray(CharSequence, int, int, Object, MissingValueProvider)
227242
*/
228243
default A parseArray(
229244
CharSequence text,
@@ -234,6 +249,7 @@ default A parseArray(
234249

235250
/**
236251
* Parse the given JSON&#x2192;URL text.
252+
* @see #parseArray(CharSequence, int, int, Object, MissingValueProvider)
237253
*/
238254
default A parseArray(
239255
CharSequence text,
@@ -250,6 +266,7 @@ default A parseArray(
250266
* @param length number of characters in {@code text} to parse
251267
* @param impliedArray a valid factory array or {@code null}
252268
* @param mvp a valid MissingValueProvider or {@code null}
269+
* @see #parseArray(JsonUrlIterator, Object, MissingValueProvider)
253270
*/
254271
default A parseArray(
255272
CharSequence text,
@@ -276,6 +293,7 @@ default A parseArray(
276293
* @param iter a valid CharIterator
277294
* @param impliedArray a valid factory array or {@code null}
278295
* @param mvp a valid MissingValueProvider or {@code null}
296+
* @see #parseArray(JsonUrlIterator, Object, MissingValueProvider)
279297
*/
280298
default A parseArray(
281299
CharIterator iter,
@@ -293,6 +311,8 @@ default A parseArray(
293311
* @param iter a valid JsonUrlIterator
294312
* @param impliedArray a valid factory array or {@code null}
295313
* @param mvp a valid MissingValueProvider or {@code null}
314+
* @see <a href="https://github.com/jsonurl/specification/#291-implied-arrays"
315+
* >JSON&#x2192;URL specification, section 2.9.1</a>
296316
*/
297317
A parseArray(
298318
JsonUrlIterator iter,

0 commit comments

Comments
 (0)