From a0f55c977403319a739e8c094064ea9166334734 Mon Sep 17 00:00:00 2001 From: Tatu Saloranta Date: Fri, 10 May 2024 15:26:11 -0700 Subject: [PATCH] Javadoc issue fixes for 2.18 (partial) --- .../fasterxml/jackson/core/JsonGenerator.java | 12 +++++++++++- .../fasterxml/jackson/core/base/ParserBase.java | 8 ++++++++ .../jackson/core/base/ParserMinimalBase.java | 6 +++++- .../core/filter/JsonPointerBasedFilter.java | 2 ++ .../jackson/core/io/ContentReference.java | 17 +++++++++++------ .../fasterxml/jackson/core/io/IOContext.java | 4 +++- .../jackson/core/util/ByteArrayBuilder.java | 2 ++ .../jackson/core/JDKSerializabilityTest.java | 1 + .../core/util/JsonBufferRecyclersTest.java | 3 +++ src/test/java/perf/RecyclerPoolTest.java | 1 + 10 files changed, 47 insertions(+), 9 deletions(-) diff --git a/src/main/java/com/fasterxml/jackson/core/JsonGenerator.java b/src/main/java/com/fasterxml/jackson/core/JsonGenerator.java index d4e18d64ba..f8ee301e2b 100644 --- a/src/main/java/com/fasterxml/jackson/core/JsonGenerator.java +++ b/src/main/java/com/fasterxml/jackson/core/JsonGenerator.java @@ -354,6 +354,8 @@ protected JsonGenerator() { } /** * Get the constraints to apply when performing streaming writes. * + * @return StreamWriteConstraints used by this generator + * * @since 2.16 */ public StreamWriteConstraints streamWriteConstraints() { @@ -2717,11 +2719,13 @@ protected void _copyCurrentContents(JsonParser p) throws IOException * {@link JsonParser#getNumberType()} for declared type and uses matching * accessors: this may cause inexact conversion for some textual formats * (depending on settings). If this is problematic, use - * {@lnik #_copyCurrentFloatValueExact} instead (note that doing so may add + * {@link #_copyCurrentFloatValueExact} instead (note that doing so may add * overhead). * * @param p Parser that points to the value to copy * + * @throws IOException exception thrown by write method called to copy value, if any + * * @since 2.15 */ protected void _copyCurrentFloatValue(JsonParser p) throws IOException @@ -2748,6 +2752,8 @@ protected void _copyCurrentFloatValue(JsonParser p) throws IOException * * @param p Parser that points to the value to copy * + * @throws IOException exception thrown by write method called to copy value, if any + * * @since 2.15 */ protected void _copyCurrentFloatValueExact(JsonParser p) throws IOException @@ -2768,6 +2774,8 @@ protected void _copyCurrentFloatValueExact(JsonParser p) throws IOException * * @param p Parser that points to the value to copy * + * @throws IOException exception thrown by write method called to copy value, if any + * * @since 2.15 */ protected void _copyCurrentIntValue(JsonParser p) throws IOException @@ -2788,6 +2796,8 @@ protected void _copyCurrentIntValue(JsonParser p) throws IOException * * @param p Parser that points to the value to copy * + * @throws IOException exception thrown by write method called to copy value, if any + * * @since 2.15 */ protected void _copyCurrentStringValue(JsonParser p) throws IOException diff --git a/src/main/java/com/fasterxml/jackson/core/base/ParserBase.java b/src/main/java/com/fasterxml/jackson/core/base/ParserBase.java index eb3b3c6442..5d5233d109 100644 --- a/src/main/java/com/fasterxml/jackson/core/base/ParserBase.java +++ b/src/main/java/com/fasterxml/jackson/core/base/ParserBase.java @@ -1251,6 +1251,8 @@ protected BigInteger _convertBigDecimalToBigInteger(BigDecimal bigDec) throws IO * * @return {@link BigInteger} value of the current token * + * @throws JsonParseException If parsing fails + * * @since 2.14 */ protected BigInteger _getBigInteger() throws JsonParseException { @@ -1277,6 +1279,8 @@ protected BigInteger _getBigInteger() throws JsonParseException { * * @return {@link BigDecimal} value of the current token * + * @throws JsonParseException If parsing fails + * * @since 2.14 */ protected BigDecimal _getBigDecimal() throws JsonParseException { @@ -1303,6 +1307,8 @@ protected BigDecimal _getBigDecimal() throws JsonParseException { * * @return {@code double} value of the current token * + * @throws JsonParseException If parsing fails + * * @since 2.15 */ protected double _getNumberDouble() throws JsonParseException { @@ -1324,6 +1330,8 @@ protected double _getNumberDouble() throws JsonParseException { * * @return {@code float} value of the current token * + * @throws JsonParseException If parsing fails + * * @since 2.15 */ protected float _getNumberFloat() throws JsonParseException { diff --git a/src/main/java/com/fasterxml/jackson/core/base/ParserMinimalBase.java b/src/main/java/com/fasterxml/jackson/core/base/ParserMinimalBase.java index e6d7b2f28d..2af049f6ab 100644 --- a/src/main/java/com/fasterxml/jackson/core/base/ParserMinimalBase.java +++ b/src/main/java/com/fasterxml/jackson/core/base/ParserMinimalBase.java @@ -690,8 +690,12 @@ protected void _reportUnexpectedChar(int ch, String comment) throws JsonParseExc * * @param ch Character that was unexpected * @param comment Additional failure comment to add, if any + * @param Nominal type for bogus return value * - * @throws JsonParseException + * @return Nothing, just declared to let caller use {@code return} when + * calling this method, to keep compiler happy. + * + * @throws JsonParseException constructed with {@link #_constructReadException(String, JsonLocation)} */ protected T _reportUnexpectedNumberChar(int ch, String comment) throws JsonParseException { String msg = String.format("Unexpected character (%s) in numeric value", _getCharDesc(ch)); diff --git a/src/main/java/com/fasterxml/jackson/core/filter/JsonPointerBasedFilter.java b/src/main/java/com/fasterxml/jackson/core/filter/JsonPointerBasedFilter.java index 4ffd947a03..d2d8bfb5a7 100644 --- a/src/main/java/com/fasterxml/jackson/core/filter/JsonPointerBasedFilter.java +++ b/src/main/java/com/fasterxml/jackson/core/filter/JsonPointerBasedFilter.java @@ -54,6 +54,8 @@ public JsonPointerBasedFilter(JsonPointer pathToMatch, boolean includeAllElement * @param includeAllElements Whether to just include all array elements * of matching Array-valued path automatically * + * @return Constructed filter + * * @since 2.16 */ protected JsonPointerBasedFilter construct(JsonPointer pathToMatch, boolean includeAllElements) { diff --git a/src/main/java/com/fasterxml/jackson/core/io/ContentReference.java b/src/main/java/com/fasterxml/jackson/core/io/ContentReference.java index 6884661b7b..9186d8dcfd 100644 --- a/src/main/java/com/fasterxml/jackson/core/io/ContentReference.java +++ b/src/main/java/com/fasterxml/jackson/core/io/ContentReference.java @@ -96,6 +96,9 @@ public class ContentReference */ /** + * @param isContentTextual Whether content is textual (not binary) + * @param rawContent Contents being referenced + * * @deprecated Since 2.16. Use {@link #ContentReference(boolean, Object, ErrorReportConfiguration)} instead. */ @Deprecated @@ -104,6 +107,11 @@ protected ContentReference(boolean isContentTextual, Object rawContent) { } /** + * @param isContentTextual Whether content is textual (not binary) + * @param rawContent Contents being referenced + * @param offset Offset of content within {@code rawContent} + * @param length Length of content within {@code rawContent} + * * @deprecated Since 2.16. Use {@link #ContentReference(boolean, Object, int, int, ErrorReportConfiguration)} instead. */ @Deprecated @@ -113,17 +121,14 @@ protected ContentReference(boolean isContentTextual, Object rawContent, this(isContentTextual, rawContent, offset, length, ErrorReportConfiguration.defaults()); } - /** - * @since 2.16 - */ + + // @since 2.16 protected ContentReference(boolean isContentTextual, Object rawContent, ErrorReportConfiguration errorReportConfiguration) { this(isContentTextual, rawContent, -1, -1, errorReportConfiguration); } - /** - * @since 2.16 - */ + // @since 2.16 protected ContentReference(boolean isContentTextual, Object rawContent, int offset, int length, ErrorReportConfiguration errorReportConfiguration) { diff --git a/src/main/java/com/fasterxml/jackson/core/io/IOContext.java b/src/main/java/com/fasterxml/jackson/core/io/IOContext.java index 6583e5f124..41ffe23e76 100644 --- a/src/main/java/com/fasterxml/jackson/core/io/IOContext.java +++ b/src/main/java/com/fasterxml/jackson/core/io/IOContext.java @@ -209,6 +209,8 @@ public IOContext(BufferRecycler br, Object rawContent, boolean managedResource) * {@link #close()}: called when {@link #_bufferRecycler} life-cycle is * externally managed. * + * @return This context instance, for call chaining + * * @since 2.17 */ public IOContext markBufferRecyclerReleased() { @@ -223,7 +225,7 @@ public IOContext markBufferRecyclerReleased() { */ /** - * @return constraints for streaming reads + * @return Constraints to use for streaming reads * @since 2.15 */ public StreamReadConstraints streamReadConstraints() { diff --git a/src/main/java/com/fasterxml/jackson/core/util/ByteArrayBuilder.java b/src/main/java/com/fasterxml/jackson/core/util/ByteArrayBuilder.java index 6ad10bac19..226932cf45 100644 --- a/src/main/java/com/fasterxml/jackson/core/util/ByteArrayBuilder.java +++ b/src/main/java/com/fasterxml/jackson/core/util/ByteArrayBuilder.java @@ -193,6 +193,8 @@ public byte[] toByteArray() * clear state; returns buffer(s) to {@link BufferRecycler} configured, * if any, and returns output to caller. * + * @return Content in byte array + * * @since 2.17 */ public byte[] getClearAndRelease() diff --git a/src/test/java/com/fasterxml/jackson/core/JDKSerializabilityTest.java b/src/test/java/com/fasterxml/jackson/core/JDKSerializabilityTest.java index b93b49140b..d160ed49ef 100644 --- a/src/test/java/com/fasterxml/jackson/core/JDKSerializabilityTest.java +++ b/src/test/java/com/fasterxml/jackson/core/JDKSerializabilityTest.java @@ -124,6 +124,7 @@ void sourceReference() throws Exception */ @Test + @Deprecated void recyclerPools() throws Exception { // First: shared/global pools that will always remain/become globally diff --git a/src/test/java/com/fasterxml/jackson/core/util/JsonBufferRecyclersTest.java b/src/test/java/com/fasterxml/jackson/core/util/JsonBufferRecyclersTest.java index 91631fbe16..ab53b79939 100644 --- a/src/test/java/com/fasterxml/jackson/core/util/JsonBufferRecyclersTest.java +++ b/src/test/java/com/fasterxml/jackson/core/util/JsonBufferRecyclersTest.java @@ -31,6 +31,7 @@ void parserWithDequeuPool() throws Exception { } @Test + @Deprecated void parserWithLockFreePool() throws Exception { _testParser(JsonRecyclerPools.newLockFreePool(), 0, 1); _testParser(JsonRecyclerPools.sharedLockFreePool(), null, null); @@ -91,6 +92,7 @@ void generatorWithDequeuPool() throws Exception { } @Test + @Deprecated void generatorWithLockFreePool() throws Exception { _testGenerator(JsonRecyclerPools.newLockFreePool(), 0, 1); _testGenerator(JsonRecyclerPools.sharedLockFreePool(), null, null); @@ -149,6 +151,7 @@ void copyWithDequeuPool() throws Exception { } @Test + @Deprecated void copyWithLockFreePool() throws Exception { _testCopy(JsonRecyclerPools.newLockFreePool()); _testCopy(JsonRecyclerPools.sharedLockFreePool()); diff --git a/src/test/java/perf/RecyclerPoolTest.java b/src/test/java/perf/RecyclerPoolTest.java index d0dc967d5a..cda98a87be 100644 --- a/src/test/java/perf/RecyclerPoolTest.java +++ b/src/test/java/perf/RecyclerPoolTest.java @@ -149,6 +149,7 @@ private void _testWrite(JsonFactory jsonF) throws Exception g.close(); } + @SuppressWarnings("deprecation") public static void main(String[] args) throws Exception { RecyclerPoolTest test = new RecyclerPoolTest(THREAD_COUNT);