From c2449381ae2be063d2016ea046b2776e62f5e1b6 Mon Sep 17 00:00:00 2001 From: David Noble Date: Tue, 17 Sep 2019 00:22:04 -0700 Subject: [PATCH] Javadoc update --- .../cosmos/serialization/hybridrow/Float128.java | 2 +- .../cosmos/serialization/hybridrow/RowBuffer.java | 2 +- .../cosmos/serialization/hybridrow/RowCursor.java | 6 +++--- .../hybridrow/codecs/DateTimeCodec.java | 2 +- .../hybridrow/codecs/DecimalCodec.java | 2 +- .../hybridrow/codecs/Float128Codec.java | 2 +- .../serialization/hybridrow/codecs/GuidCodec.java | 2 +- .../hybridrow/internal/Murmur3Hash.java | 2 +- .../hybridrow/layouts/LayoutBit.java | 14 ++++++++------ .../hybridrow/layouts/LayoutCodeTraits.java | 4 ++-- .../hybridrow/layouts/LayoutColumn.java | 12 ++++++------ .../hybridrow/layouts/LayoutCompiler.java | 6 +++--- .../hybridrow/layouts/LayoutListReadable.java | 2 +- .../hybridrow/layouts/LayoutListWritable.java | 2 +- .../hybridrow/layouts/LayoutTypePrimitive.java | 2 +- .../hybridrow/layouts/LayoutTypeScope.java | 2 +- .../hybridrow/layouts/LayoutUtf8Readable.java | 2 +- .../hybridrow/layouts/LayoutUtf8Writable.java | 2 +- .../hybridrow/schemas/ArrayPropertyType.java | 2 +- .../hybridrow/schemas/MapPropertyType.java | 4 ++-- .../hybridrow/schemas/TaggedPropertyType.java | 15 +++++++-------- 21 files changed, 45 insertions(+), 44 deletions(-) diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/Float128.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/Float128.java index 82f6262..aeb75d4 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/Float128.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/Float128.java @@ -7,7 +7,7 @@ package com.azure.data.cosmos.serialization.hybridrow; * Represents an IEEE 754-2008 128-bit decimal floating point number. *

* The {@link Float128} represents an IEEE 754-2008 floating point number as a pair of {@code long} values: - * {@link #high} and {@link #low}. + * {@link #high()} and {@link #low()}. * * @see decimal128 floating-point format * @see 754-2008: IEEE Standard for Floating-Point Arithmetic diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/RowBuffer.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/RowBuffer.java index 1d216a4..9e476f9 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/RowBuffer.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/RowBuffer.java @@ -3684,7 +3684,7 @@ public final class RowBuffer { /** * Represents a single item within a set/map scope that needs to be indexed. *

- * This structure is used when rebuilding a set/map index during row streaming via {@link RowWriter}.Each item + * This structure is used when rebuilding a set/map index during row streaming via {@link RowWriter}. Each item * encodes its offsets and length within the row. */ static final class UniqueIndexItem { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/RowCursor.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/RowCursor.java index 3a369de..ae133c6 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/RowCursor.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/RowCursor.java @@ -89,7 +89,7 @@ public final class RowCursor implements Cloneable { /** * Sets the layout type of an existing field. * - * @param value a {@link LayoutType layout type}. + * @param value a {@link LayoutType}. * @return a reference to this {@link RowCursor}. */ public RowCursor cellType(LayoutType value) { @@ -100,7 +100,7 @@ public final class RowCursor implements Cloneable { /** * For types with generic parameters (e.g. {@link LayoutTuple}, the type parameters. * - * @return a {@link TypeArgumentList type argument argument list} or {@code null}. + * @return a {@link TypeArgumentList} or {@code null}. */ public TypeArgumentList cellTypeArgs() { return this.cellTypeArgs; @@ -109,7 +109,7 @@ public final class RowCursor implements Cloneable { /** * Sets the layout type arguments of an existing field. * - * @param value a {@link TypeArgumentList type argument argument list}. + * @param value a {@link TypeArgumentList} or {@code null}. * @return a reference to this {@link RowCursor}. */ public RowCursor cellTypeArgs(TypeArgumentList value) { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/DateTimeCodec.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/DateTimeCodec.java index 50ec1c4..53254a6 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/DateTimeCodec.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/DateTimeCodec.java @@ -62,7 +62,7 @@ public final class DateTimeCodec { /** * Decode an {@link OffsetDateTime} serialized like a {@code System.DateTime} by {@code MemoryMarshal.Write}. * - * @param bytes a {@link byte} array containing the serialized value to be decoded. + * @param bytes an array containing the serialized value to be decoded. * @return a new {@link OffsetDateTime}. * @see struct DateTime source */ diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/DecimalCodec.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/DecimalCodec.java index 207f52e..d8ecb07 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/DecimalCodec.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/DecimalCodec.java @@ -64,7 +64,7 @@ public final class DecimalCodec { /** * Decode an {@link BigDecimal} serialized like a {@code System.Decimal} by {@code MemoryMarshal.Write}. * - * @param bytes a {@link byte} array containing the serialized {@code System.Decimal} to be decoded. + * @param bytes an array containing the serialized {@code System.Decimal} to be decoded. * @return a new {@link BigDecimal}. * @see struct Decimal source */ diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/Float128Codec.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/Float128Codec.java index da61bdc..8bc78ae 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/Float128Codec.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/Float128Codec.java @@ -22,7 +22,7 @@ public final class Float128Codec { /** * Decode a {@link Float128} from a sequence of two {@code long}s in little endian format. * - * @param bytes a {@link byte} array containing the serialized {@link Float128} to be decoded. + * @param bytes an array containing the serialized {@link Float128} to be decoded. * @return a new {@link Float128}. */ public static Float128 decode(@Nonnull final byte[] bytes) { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/GuidCodec.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/GuidCodec.java index 5aeae39..4a79b16 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/GuidCodec.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/codecs/GuidCodec.java @@ -56,7 +56,7 @@ public final class GuidCodec { /** * Decode a {@link UUID} serialized like a {@code System.Guid} by {@code MemoryMarshal.Write}. * - * @param bytes a {@link byte} array containing the serialized {@link UUID} to be decoded. + * @param bytes an array containing the serialized {@link UUID} to be decoded. * @return a new {@link UUID}. */ public static UUID decode(@Nonnull final byte[] bytes) { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/internal/Murmur3Hash.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/internal/Murmur3Hash.java index 1f077ac..6805335 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/internal/Murmur3Hash.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/internal/Murmur3Hash.java @@ -62,7 +62,7 @@ public final class Murmur3Hash { } /** - * Computes a 128-bit Murmur3Hash 128-bit value for a {@link boolean} data item. + * Computes a 128-bit Murmur3Hash 128-bit value for a {@code boolean} data item. * * @param item The data to hash. * @param seed The seed with which to initialize. diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutBit.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutBit.java index ec93665..49cfc39 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutBit.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutBit.java @@ -14,7 +14,7 @@ public final class LayoutBit { private final int index; /** - * Initializes a new instance of the {@link LayoutBit} struct. + * Initializes a new instance of the {@link LayoutBit} class. * * @param index The zero-based offset into the layout bitmask. */ @@ -35,9 +35,9 @@ public final class LayoutBit { } /** - * Zero-based bit from the beginning of the byte that contains this bit + * Zero-based bit from the beginning of the byte that contains this bit. *

- * Also see {@link #offset} to identify relevant byte. + * Also see {@link #offset(int)} to identify relevant byte. * * @return The bit of the byte within the bitmask. */ @@ -46,7 +46,9 @@ public final class LayoutBit { } /** - * Zero-based offset into the layout bitmask + * Zero-based offset into the layout bitmask. + * + * @return zero-based offset into the layout bitmask. */ public int index() { return this.index; @@ -57,9 +59,9 @@ public final class LayoutBit { } /** - * Returns the zero-based byte offset from the beginning of the row or scope that contains the bit from the bitmask + * Returns the zero-based byte offset from the beginning of the row or scope that contains the bit from the bitmask. *

- * Also see {@link #bit} to identify. + * Also see {@link #bit()} to identify. * * @param offset The byte offset from the beginning of the row where the scope begins. * @return The byte offset containing this bit. diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCodeTraits.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCodeTraits.java index b950d54..fb6c5c3 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCodeTraits.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCodeTraits.java @@ -16,12 +16,12 @@ public final class LayoutCodeTraits { } /** - * Returns a canonicalized version of the specified layout code + * Returns a canonicalized version of the specified layout code. *

* Some codes (e.g. {@link LayoutCode#BOOLEAN} use multiple type codes to also encode values. This function converts * actual value based code into the canonicalized type code for schema comparisons. * - * @param code The code to canonicalize + * @param code The code to canonicalize. */ public static LayoutCode canonicalize(LayoutCode code) { return (code == LayoutCode.BOOLEAN_FALSE) ? LayoutCode.BOOLEAN : code; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutColumn.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutColumn.java index 77da86e..17b38ec 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutColumn.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutColumn.java @@ -77,8 +77,8 @@ public final class LayoutColumn { /** * Full logical path of the field within the row *

- * Paths are expressed in dotted notation: e.g. a relative {@link #path} of 'b.c' within the scope 'a' yields a - * {@link #fullPath} of 'a.b.c'. + * Paths are expressed in dotted notation: e.g. a relative {@link #path()} of 'b.c' within the scope 'a' yields a + * full path of 'a.b.c'. */ public @Nonnull Utf8String fullPath() { return this.fullPath; @@ -101,12 +101,12 @@ public final class LayoutColumn { } /** - * If {@link #storage} equals {@link StorageKind#FIXED} then the byte offset to the field location. + * If {@link #storage()} equals {@link StorageKind#FIXED} then the byte offset to the field location. *

- * If {@link #storage} equals {@link StorageKind#VARIABLE} then the zero-based index of the field from the + * If {@link #storage()} equals {@link StorageKind#VARIABLE} then the zero-based index of the field from the * beginning of the variable length segment. *

- * For all other values of {@link #storage}, {@link #offset} is ignored. + * For all other values of {@link #storage()}, {@code offset} is ignored. */ public int offset() { return this.offset; @@ -130,7 +130,7 @@ public final class LayoutColumn { } /** - * If {@link LayoutType#isBoolean} then the zero-based extra index within the bool byte + * If {@link LayoutType#isBoolean()} then the zero-based extra index within the bool byte * holding the value of this type, otherwise must be 0. */ public int size() { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCompiler.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCompiler.java index 9992744..5ecf1cf 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCompiler.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCompiler.java @@ -350,12 +350,12 @@ public final class LayoutCompiler { assert logicalType instanceof TaggedPropertyType; TaggedPropertyType tg = (TaggedPropertyType) logicalType; - if (tg.items().size() < TaggedPropertyType.MinTaggedArguments || (tg.items().size() > TaggedPropertyType.MaxTaggedArguments)) { + if (tg.items().size() < TaggedPropertyType.MIN_TAGGED_ARGUMENTS || (tg.items().size() > TaggedPropertyType.MAX_TAGGED_ARGUMENTS)) { throw new LayoutCompilationException(lenientFormat( "Invalid number of arguments in Tagged: %s <= %s <= %s", - TaggedPropertyType.MinTaggedArguments, + TaggedPropertyType.MIN_TAGGED_ARGUMENTS, tg.items().size(), - TaggedPropertyType.MaxTaggedArguments + TaggedPropertyType.MAX_TAGGED_ARGUMENTS )); } diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutListReadable.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutListReadable.java index bff1521..be03f88 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutListReadable.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutListReadable.java @@ -11,7 +11,7 @@ import com.azure.data.cosmos.serialization.hybridrow.RowCursor; import java.util.List; /** - * An optional interface that indicates a {@link LayoutType{T}} can also read using a read-only {@link List{T}} + * An optional interface that indicates a {@link LayoutType} can also read using a read-only {@link List} * * @param The sub-element type to be written */ diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutListWritable.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutListWritable.java index e95fead..bcacbcc 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutListWritable.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutListWritable.java @@ -10,7 +10,7 @@ import com.azure.data.cosmos.serialization.hybridrow.RowCursor; import java.util.List; /** - * An optional interface that indicates a {@link LayoutType{T}} can also write using a {@link List{T}} + * An optional interface that indicates a {@link LayoutType} can also write using a {@link List} * * @param The sub-element type to be written */ diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypePrimitive.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypePrimitive.java index b7a6797..5292f8f 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypePrimitive.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypePrimitive.java @@ -15,7 +15,7 @@ import static com.google.common.base.Preconditions.checkNotNull; public abstract class LayoutTypePrimitive extends LayoutType implements ILayoutType { /** - * Initializes a new instance of the {@link LayoutType} class. + * Initializes a new instance of the {@link LayoutTypePrimitive} class. * * @param code * @param immutable diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypeScope.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypeScope.java index 67adf1a..cae9939 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypeScope.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypeScope.java @@ -104,7 +104,7 @@ public abstract class LayoutTypeScope extends LayoutType { * {@code true} if writing an item in the specified typed scope would elide the type code because it is implied by * the type arguments * - * @param edit a non-null {@link RowCursor} specifying a typed scope + * @param edit a non-null {@link RowCursor} specifying a typed scope. * @return {@code true} if the type code is implied (not written); {@code false} otherwise. */ public boolean hasImplicitTypeCode(@Nonnull final RowCursor edit) { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUtf8Readable.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUtf8Readable.java index 0d8943b..5586d6d 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUtf8Readable.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUtf8Readable.java @@ -12,7 +12,7 @@ import com.azure.data.cosmos.serialization.hybridrow.RowCursor; import javax.annotation.Nonnull; /** - * An optional interface that indicates a {@link LayoutType{T}} can also be read as a {@link Utf8String}. + * An optional interface that indicates a {@link LayoutType} can also be read as a {@link Utf8String}. */ public interface LayoutUtf8Readable extends ILayoutType { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUtf8Writable.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUtf8Writable.java index 09b2625..08cc202 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUtf8Writable.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUtf8Writable.java @@ -11,7 +11,7 @@ import com.azure.data.cosmos.serialization.hybridrow.RowCursor; import javax.annotation.Nonnull; /** - * An optional interface that indicates a {@link LayoutType{T}} can also write using a {@link Utf8String} + * An optional interface that indicates a {@link LayoutType} can also write using a {@link Utf8String} */ public interface LayoutUtf8Writable extends ILayoutType { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ArrayPropertyType.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ArrayPropertyType.java index 42ef572..ccd892d 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ArrayPropertyType.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ArrayPropertyType.java @@ -7,7 +7,7 @@ package com.azure.data.cosmos.serialization.hybridrow.schemas; * Array properties represent an unbounded set of zero or more items. *

* Arrays may be typed or untyped. Within typed arrays, all items MUST be the same type. The type of items is specified - * via {@link #items}. Typed arrays may be stored more efficiently than untyped arrays. When {@link #items} is + * via {@link #items()}. Typed arrays may be stored more efficiently than untyped arrays. When {@link #items()} is * unspecified, the array is untyped and its items may be heterogeneous. */ public class ArrayPropertyType extends ScopePropertyType { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/MapPropertyType.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/MapPropertyType.java index f939e55..cbab255 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/MapPropertyType.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/MapPropertyType.java @@ -7,8 +7,8 @@ package com.azure.data.cosmos.serialization.hybridrow.schemas; * Map properties represent an unbounded set of zero or more key-value pairs with unique keys. *

* Maps are typed or untyped. Within typed maps, all key MUST be the same type, and all values MUST be the same type. - * The type of both key and values is specified via {@link #keys} and {@link #values} respectively. Typed maps may be - * stored more efficiently than untyped maps. When {@link #keys} or {@link #values} is unspecified or marked + * The type of both key and values is specified via {@link #keys()} and {@link #values()} respectively. Typed maps may + * be stored more efficiently than untyped maps. When {@link #keys()} or {@link #values()} is unspecified or marked * {@link TypeKind#ANY}, the map is untyped and its key and/or values may be heterogeneous. */ public class MapPropertyType extends ScopePropertyType { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/TaggedPropertyType.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/TaggedPropertyType.java index 89cba60..cd19630 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/TaggedPropertyType.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/TaggedPropertyType.java @@ -10,27 +10,26 @@ import java.util.List; * Tagged properties pair one or more typed values with an API-specific uint8 type code. *

* The {@code UInt8} type code is implicitly in position 0 within the resulting tagged and should not be specified in - * {@link #items}. + * {@link #items()}. */ public class TaggedPropertyType extends ScopePropertyType { - public static final int MaxTaggedArguments = 2; - public static final int MinTaggedArguments = 1; - /** - * Types of the elements of the tagged in element order. - */ + public static final int MAX_TAGGED_ARGUMENTS = 2; + public static final int MIN_TAGGED_ARGUMENTS = 1; + private List items; /** * Initializes a new instance of the {@link TaggedPropertyType} class. */ public TaggedPropertyType() { - this.items = new ArrayList(); + this.items = new ArrayList<>(); } /** * Types of the elements of the tagged in element order. - * @return + * + * @return a list of property types. */ public final List items() { return this.items;