From 2493625b18d2e99f1747808c8e4d3d69e2629406 Mon Sep 17 00:00:00 2001 From: Tatu Saloranta Date: Mon, 4 Jan 2021 18:15:07 -0800 Subject: [PATCH] Yet more javadoc'ing --- .../jackson/core/SerializableString.java | 16 +-- .../jackson/core/io/InputDecorator.java | 10 +- .../jackson/core/json/DupDetector.java | 14 +++ .../jackson/core/json/JsonReadFeature.java | 2 + .../jackson/core/json/JsonWriteFeature.java | 2 + .../jackson/core/util/JacksonFeatureSet.java | 5 +- .../core/util/MinimalPrettyPrinter.java | 2 + .../jackson/core/util/TextBuffer.java | 114 ++++++++++++++---- .../jackson/core/util/VersionUtil.java | 41 ++++--- 9 files changed, 156 insertions(+), 50 deletions(-) diff --git a/src/main/java/com/fasterxml/jackson/core/SerializableString.java b/src/main/java/com/fasterxml/jackson/core/SerializableString.java index 79ed83c79b..d726a3bf9e 100644 --- a/src/main/java/com/fasterxml/jackson/core/SerializableString.java +++ b/src/main/java/com/fasterxml/jackson/core/SerializableString.java @@ -157,9 +157,9 @@ public interface SerializableString /** * Method for writing JSON-escaped UTF-8 encoded String value using given - * {@link OutputStream}. + * {@link java.io.OutputStream}. * - * @param out {@link OutputStream} to write String into + * @param out {@link java.io.OutputStream} to write String into * * @return Number of bytes written * @@ -169,9 +169,9 @@ public interface SerializableString /** * Method for writing unescaped UTF-8 encoded String value using given - * {@link OutputStream}. + * {@link java.io.OutputStream}. * - * @param out {@link OutputStream} to write String into + * @param out {@link java.io.OutputStream} to write String into * * @return Number of bytes written * @@ -181,9 +181,9 @@ public interface SerializableString /** * Method for appending JSON-escaped UTF-8 encoded String value into given - * {@link ByteBuffer}, if it fits. + * {@link java.nio.ByteBuffer}, if it fits. * - * @param buffer {@link ByteBuffer} to append String into + * @param buffer {@link java.nio.ByteBuffer} to append String into * * @return Number of bytes put, if contents fit, otherwise -1 * @@ -193,9 +193,9 @@ public interface SerializableString /** * Method for appending unquoted ('raw') UTF-8 encoded String value into given - * {@link ByteBuffer}, if it fits. + * {@link java.nio.ByteBuffer}, if it fits. * - * @param buffer {@link ByteBuffer} to append String into + * @param buffer {@link java.nio.ByteBuffer} to append String into * * @return Number of bytes put, if contents fit, otherwise -1 * diff --git a/src/main/java/com/fasterxml/jackson/core/io/InputDecorator.java b/src/main/java/com/fasterxml/jackson/core/io/InputDecorator.java index eb98a8c73f..cb774f4eed 100644 --- a/src/main/java/com/fasterxml/jackson/core/io/InputDecorator.java +++ b/src/main/java/com/fasterxml/jackson/core/io/InputDecorator.java @@ -26,6 +26,8 @@ public abstract class InputDecorator * * @return InputStream to use; either 'in' as is, or decorator * version that typically delogates to 'in' + * + * @throws IOException if construction of {@link InputStream} fails */ public abstract InputStream decorate(IOContext ctxt, InputStream in) throws IOException; @@ -46,6 +48,8 @@ public abstract InputStream decorate(IOContext ctxt, InputStream in) * * @return Either {@link InputStream} to use as input source; or null to indicate * that contents are to be processed as-is by caller + * + * @throws IOException if construction of {@link InputStream} fails */ public abstract InputStream decorate(IOContext ctxt, byte[] src, int offset, int length) throws IOException; @@ -65,7 +69,9 @@ public abstract InputStream decorate(IOContext ctxt, byte[] src, int offset, int * * @return InputStream to use; either 'input' as is, or decorator * version that typically delogates to 'input' - * + * + * @throws IOException if construction of {@link DataInput} fails + * * @since 2.8 */ public DataInput decorate(IOContext ctxt, DataInput input) @@ -86,6 +92,8 @@ public DataInput decorate(IOContext ctxt, DataInput input) * * @return Reader to use; either passed in argument, or something that * calls it (for example, a {@link FilterReader}) + * + * @throws IOException if construction of {@link Reader} fails */ public abstract Reader decorate(IOContext ctxt, Reader r) throws IOException; } diff --git a/src/main/java/com/fasterxml/jackson/core/json/DupDetector.java b/src/main/java/com/fasterxml/jackson/core/json/DupDetector.java index e02150c228..7b6dc4678f 100644 --- a/src/main/java/com/fasterxml/jackson/core/json/DupDetector.java +++ b/src/main/java/com/fasterxml/jackson/core/json/DupDetector.java @@ -65,12 +65,26 @@ public JsonLocation findLocation() { } /** + * @return Source object (parser / generator) used to construct this detector + * * @since 2.7 */ public Object getSource() { return _source; } + /** + * Method called to check whether a newly encountered property name would + * be a duplicate within this context, and if not, update the state to remember + * having seen the property name for checking more property names + * + * @param name Property seen + * + * @return {@code True} if the property had already been seen before in this context + * + * @throws JsonParseException to report possible operation problem (default implementation + * never throws it) + */ public boolean isDup(String name) throws JsonParseException { if (_firstName == null) { diff --git a/src/main/java/com/fasterxml/jackson/core/json/JsonReadFeature.java b/src/main/java/com/fasterxml/jackson/core/json/JsonReadFeature.java index 82ad94ab99..304b320a12 100644 --- a/src/main/java/com/fasterxml/jackson/core/json/JsonReadFeature.java +++ b/src/main/java/com/fasterxml/jackson/core/json/JsonReadFeature.java @@ -196,6 +196,8 @@ public enum JsonReadFeature /** * Method that calculates bit set (flags) of all features that * are enabled by default. + * + * @return Bit mask of all features that are enabled by default */ public static int collectDefaults() { diff --git a/src/main/java/com/fasterxml/jackson/core/json/JsonWriteFeature.java b/src/main/java/com/fasterxml/jackson/core/json/JsonWriteFeature.java index 29b2a8f59d..41f6845ce5 100644 --- a/src/main/java/com/fasterxml/jackson/core/json/JsonWriteFeature.java +++ b/src/main/java/com/fasterxml/jackson/core/json/JsonWriteFeature.java @@ -108,6 +108,8 @@ public enum JsonWriteFeature /** * Method that calculates bit set (flags) of all features that * are enabled by default. + * + * @return Bit mask of all features that are enabled by default */ public static int collectDefaults() { diff --git a/src/main/java/com/fasterxml/jackson/core/util/JacksonFeatureSet.java b/src/main/java/com/fasterxml/jackson/core/util/JacksonFeatureSet.java index 94a216b2f4..8af982b59b 100644 --- a/src/main/java/com/fasterxml/jackson/core/util/JacksonFeatureSet.java +++ b/src/main/java/com/fasterxml/jackson/core/util/JacksonFeatureSet.java @@ -27,9 +27,10 @@ protected JacksonFeatureSet(int bitmask) { * "Default" factory which will calculate settings based on default-enabled * status of all features. * - * @param Self-reference for convenience + * @param Self-reference type for convenience * - * @param allFeatures Set of all features (enabled or disabled): usually from {@code Enum.values()} + * @param allFeatures Set of all features (enabled or disabled): usually from + * {@code Enum.values()} * * @return Feature set instance constructed */ diff --git a/src/main/java/com/fasterxml/jackson/core/util/MinimalPrettyPrinter.java b/src/main/java/com/fasterxml/jackson/core/util/MinimalPrettyPrinter.java index 411662bbc9..c6d74ab2f5 100644 --- a/src/main/java/com/fasterxml/jackson/core/util/MinimalPrettyPrinter.java +++ b/src/main/java/com/fasterxml/jackson/core/util/MinimalPrettyPrinter.java @@ -56,6 +56,8 @@ public void setRootValueSeparator(String sep) { /** * @param separators Separator definitions * + * @return This pretty-printer instance to allow call chaining + * * @since 2.9 */ public MinimalPrettyPrinter setSeparators(Separators separators) { diff --git a/src/main/java/com/fasterxml/jackson/core/util/TextBuffer.java b/src/main/java/com/fasterxml/jackson/core/util/TextBuffer.java index 12af044700..86c733c08a 100644 --- a/src/main/java/com/fasterxml/jackson/core/util/TextBuffer.java +++ b/src/main/java/com/fasterxml/jackson/core/util/TextBuffer.java @@ -89,7 +89,7 @@ public final class TextBuffer // // // Currently used segment; not (yet) contained in _seqments /** - * Amount of characters in segments in {@link _segments} + * Amount of characters in segments in {@link #_segments} */ private int _segmentSize; @@ -124,9 +124,7 @@ public TextBuffer(BufferRecycler allocator) { _allocator = allocator; } - /** - * @since 2.10 - */ + // @since 2.10 protected TextBuffer(BufferRecycler allocator, char[] initialSegment) { _allocator = allocator; _currentSegment = initialSegment; @@ -138,6 +136,11 @@ protected TextBuffer(BufferRecycler allocator, char[] initialSegment) { * Factory method for constructing an instance with no allocator, and * with initial full segment. * + * @param initialSegment Initial, full segment to use for creating buffer (buffer + * {@link #size()} would return length of {@code initialSegment}) + * + * @return TextBuffer constructed + * * @since 2.10 */ public static TextBuffer fromInitial(char[] initialSegment) { @@ -204,6 +207,11 @@ public void resetWithEmpty() } /** + * Method for clearing out possibly existing content, and replacing them with + * a single-character content (so {@link #size()} would return {@code 1}) + * + * @param ch Character to set as the buffer contents + * * @since 2.9 */ public void resetWith(char ch) @@ -228,8 +236,12 @@ public void resetWith(char ch) * this means that buffer will just have pointers to actual data. It * also means that if anything is to be appended to the buffer, it * will first have to unshare it (make a local copy). + * + * @param buf Buffer that contains shared contents + * @param offset Offset of the first content character in {@code buf} + * @param len Length of content in {@code buf} */ - public void resetWithShared(char[] buf, int start, int len) + public void resetWithShared(char[] buf, int offset, int len) { // First, let's clear intermediate values, if any: _resultString = null; @@ -237,7 +249,7 @@ public void resetWithShared(char[] buf, int start, int len) // Then let's mark things we need about input buffer _inputBuffer = buf; - _inputStart = start; + _inputStart = offset; _inputLen = len; // And then reset internal input buffers, if necessary: @@ -246,7 +258,7 @@ public void resetWithShared(char[] buf, int start, int len) } } - public void resetWithCopy(char[] buf, int start, int len) + public void resetWithCopy(char[] buf, int offset, int len) { _inputBuffer = null; _inputStart = -1; // indicates shared buffer not used @@ -262,12 +274,10 @@ public void resetWithCopy(char[] buf, int start, int len) _currentSegment = buf(len); } _currentSize = _segmentSize = 0; - append(buf, start, len); + append(buf, offset, len); } - /** - * @since 2.9 - */ + // @since 2.9 public void resetWithCopy(String text, int start, int len) { _inputBuffer = null; @@ -303,16 +313,19 @@ public void resetWithString(String value) } /** + * Method for accessing the currently active (last) content segment + * without changing state of the buffer + * + * @return Currently active (last) content segment + * * @since 2.9 */ public char[] getBufferWithoutReset() { return _currentSegment; } - /** - * Helper method used to find a buffer to use, ideally one - * recycled earlier. - */ + // Helper method used to find a buffer to use, ideally one + // recycled earlier. private char[] buf(int needed) { if (_allocator != null) { @@ -342,7 +355,7 @@ private void clearSegments() */ /** - * @return Number of characters currently stored by this collector + * @return Number of characters currently stored in this buffer */ public int size() { if (_inputStart >= 0) { // shared copy from input buf @@ -369,6 +382,9 @@ public int getTextOffset() { /** * Method that can be used to check whether textual contents can * be efficiently accessed using {@link #getTextBuffer}. + * + * @return {@code True} if access via {@link #getTextBuffer()} would be efficient + * (that is, content already available as aggregated {@code char[]}) */ public boolean hasTextAsCharacters() { @@ -380,9 +396,11 @@ public boolean hasTextAsCharacters() } /** - * Accessor that may be used to get the contents of this buffer in a single - * char array regardless of whether they were collected in a segmented - * fashion or not. + * Accessor that may be used to get the contents of this buffer as a single + * {@code char[]} regardless of whether they were collected in a segmented + * fashion or not: this typically require allocation of the result buffer. + * + * @return Aggregated {@code char[]} that contains all buffered content */ public char[] getTextBuffer() { @@ -406,6 +424,13 @@ public char[] getTextBuffer() /********************************************************** */ + /** + * Accessor that may be used to get the contents of this buffer as a single + * {@code String} regardless of whether they were collected in a segmented + * fashion or not: this typically require construction of the result String. + * + * @return Aggregated buffered contents as a {@link java.lang.String} + */ public String contentsAsString() { if (_resultString == null) { @@ -457,6 +482,10 @@ public char[] contentsAsArray() { /** * Convenience method for converting contents of the buffer * into a {@link BigDecimal}. + * + * @return Buffered text value parsed as a {@link BigDecimal}, if possible + * + * @throws NumberFormatException if contents are not a valid Java number */ public BigDecimal contentsAsDecimal() throws NumberFormatException { @@ -479,6 +508,10 @@ public BigDecimal contentsAsDecimal() throws NumberFormatException /** * Convenience method for converting contents of the buffer * into a Double value. + * + * @return Buffered text value parsed as a {@link Double}, if possible + * + * @throws NumberFormatException if contents are not a valid Java number */ public double contentsAsDouble() throws NumberFormatException { return NumberInput.parseDouble(contentsAsString()); @@ -487,9 +520,16 @@ public double contentsAsDouble() throws NumberFormatException { /** * Specialized convenience method that will decode a 32-bit int, * of at most 9 digits (and possible leading minus sign). + *

+ * NOTE: method DOES NOT verify that the contents actually are a valid + * Java {@code int} value (either regarding format, or value range): caller + * MUST validate that. * * @param neg Whether contents start with a minus sign * + * @return Buffered text value parsed as an {@code int} using + * {@link NumberInput#parseInt(String)} method (which does NOT validate input) + * * @since 2.9 */ public int contentsAsInt(boolean neg) { @@ -508,9 +548,16 @@ public int contentsAsInt(boolean neg) { /** * Specialized convenience method that will decode a 64-bit int, * of at most 18 digits (and possible leading minus sign). + *

+ * NOTE: method DOES NOT verify that the contents actually are a valid + * Java {@code long} value (either regarding format, or value range): caller + * MUST validate that. * * @param neg Whether contents start with a minus sign * + * @return Buffered text value parsed as an {@code long} using + * {@link NumberInput#parseLong(String)} method (which does NOT validate input) + * * @since 2.9 */ public long contentsAsLong(boolean neg) { @@ -527,6 +574,14 @@ public long contentsAsLong(boolean neg) { } /** + * Accessor that will write buffered contents using given {@link Writer}. + * + * @param w Writer to use for writing out buffered content + * + * @return Number of characters written (same as {@link #size()}) + * + * @throws IOException If write using {@link Writer} parameter fails + * * @since 2.8 */ public int contentsToWriter(Writer w) throws IOException @@ -720,6 +775,15 @@ public char[] emptyAndGetCurrentSegment() public void setCurrentLength(int len) { _currentSize = len; } /** + * Convenience method that finishes the current active content segment + * (by specifying how many characters within consists of valid content) + * and aggregates and returns resulting contents (similar to a call + * to {@link #contentsAsString()}). + * + * @param len Length of content (in characters) of the current active segment + * + * @return String that contains all buffered content + * * @since 2.6 */ public String setCurrentAndReturn(int len) { @@ -761,6 +825,9 @@ public char[] finishCurrentSegment() { * Method called to expand size of the current segment, to * accommodate for more contiguous content. Usually only * used when parsing tokens like names if even then. + * Method will both expand the segment and return it + * + * @return Expanded current segment */ public char[] expandCurrentSegment() { @@ -782,7 +849,9 @@ public char[] expandCurrentSegment() * * @param minSize Required minimum strength of the current segment * - * @since 2.4.0 + * @return Expanded current segment + * + * @since 2.4 */ public char[] expandCurrentSegment(int minSize) { char[] curr = _currentSegment; @@ -835,10 +904,7 @@ private void unshare(int needExtra) _currentSize = sharedLen; } - /** - * Method called when current segment is full, to allocate new - * segment. - */ + // Method called when current segment is full, to allocate new segment. private void expand(int minNewSegmentSize) { // First, let's move current segment to segment list: diff --git a/src/main/java/com/fasterxml/jackson/core/util/VersionUtil.java b/src/main/java/com/fasterxml/jackson/core/util/VersionUtil.java index 33f4229e11..7df9a600bd 100644 --- a/src/main/java/com/fasterxml/jackson/core/util/VersionUtil.java +++ b/src/main/java/com/fasterxml/jackson/core/util/VersionUtil.java @@ -28,9 +28,9 @@ public class VersionUtil private final static Pattern V_SEP = Pattern.compile("[-_./;:]"); /* - /********************************************************** + /********************************************************************** /* Instance life-cycle - /********************************************************** + /********************************************************************** */ protected VersionUtil() { } @@ -39,24 +39,22 @@ protected VersionUtil() { } public Version version() { return Version.unknownVersion(); } /* - /********************************************************** + /********************************************************************** /* Static load methods - /********************************************************** + /********************************************************************** */ /** - * Helper method that will try to load version information for specified - * class. Implementation is as follows: + * Alias of {@link #packageVersionFor(Class)}. * - * First, tries to load version info from a class named - * "PackageVersion" in the same package as the class. + * @param cls Class for which to look version information * - * If no version information is found, {@link Version#unknownVersion()} is returned. + * @return Version information discovered if any; + * {@link Version#unknownVersion()} if none */ public static Version versionFor(Class cls) { - Version version = packageVersionFor(cls); - return version == null ? Version.unknownVersion() : version; + return packageVersionFor(cls); } /** @@ -64,7 +62,13 @@ public static Version versionFor(Class cls) * "PackageVersion" in the same package as the given class. *

* If the class could not be found or does not have a public - * static Version field named "VERSION", returns null. + * static Version field named "VERSION", returns "empty" {@link Version} + * returned by {@link Version#unknownVersion()}. + * + * @param cls Class for which to look version information + * + * @return Version information discovered if any; + * {@link Version#unknownVersion()} if none */ public static Version packageVersionFor(Class cls) { @@ -123,6 +127,13 @@ public static Version mavenVersionFor(ClassLoader cl, String groupId, String art /** * Method used by PackageVersion classes to decode version injected by Maven build. + * + * @param s Version String to parse + * @param groupId Maven group id to include with version + * @param artifactId Maven artifact id to include with version + * + * @return Version instance constructed from parsed components, if successful; + * {@link Version#unknownVersion()} if parsing of components fail */ public static Version parseVersion(String s, String groupId, String artifactId) { @@ -152,11 +163,11 @@ private final static void _close(Closeable c) { c.close(); } catch (IOException e) { } } - + /* - /********************************************************** + /********************************************************************** /* Orphan utility methods - /********************************************************** + /********************************************************************** */ public final static void throwInternal() {