Addressed a number of javadoc issues and the javadocs now build.

java/src/main/java/com/azure/data/cosmos/core/UtfAnyString.java

@@ -41,6 +41,8 @@ public final class UtfAnyString implements CharSequence, Comparable<UtfAnyString
 
     /**
      * {@code true} if the {@link UtfAnyString} is empty.
+     *
+     * @return {@code true} if the {@link UtfAnyString} is empty.
      */
     public boolean isEmpty() {
         return this.buffer != null && this.buffer.length() == 0;
@@ -48,15 +50,27 @@ public final class UtfAnyString implements CharSequence, Comparable<UtfAnyString
 
     /**
      * {@code true} if the {@link UtfAnyString} is {@code null}.
+     *
+     * @return {@code true} if the {@link UtfAnyString} is {@code null}.
      */
     public boolean isNull() {
         return null == this.buffer;
     }
 
+    /**
+     * {@code true} if the underlying representation of the {@link UtfAnyString} is a {@link String}.
+     *
+     * @return {@code true} if the underlying representation of the {@link UtfAnyString} is a {@link String}.
+     */
     public boolean isUtf16() {
         return this.buffer instanceof String;
     }
 
+    /**
+     * {@code true} if the underlying representation of the {@link UtfAnyString} is a {@link Utf8String}.
+     *
+     * @return {@code true} if the underlying representation of the {@link UtfAnyString} is a {@link Utf8String}.
+     */
     public boolean isUtf8() {
         return this.buffer instanceof Utf8String;
     }

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/Layout.java

@@ -141,6 +141,8 @@ public final class Layout {
      * Name of the layout.
      * <p>
      * Usually this is the name of the {@link Schema} from which this {@link Layout} was generated.
+     *
+     * @return name of the layout.
      */
     public String name() {
         return this.name;
@@ -151,6 +153,8 @@ public final class Layout {
      * <p>
      * A presence bit is allocated for each fixed and variable-length field.  Sparse columns never have presence bits.
      * Fixed boolean allocate an additional bit from the bitmask to store their value.
+     *
+     * @return the number of bit mask bytes allocated with the layout.
      */
     public int numBitmaskBytes() {
         return this.numBitmaskBytes;
@@ -158,6 +162,8 @@ public final class Layout {
 
     /**
      * The number of fixed columns.
+     *
+     * @return the number of fixed columns.
      */
     public int numFixed() {
         return this.numFixed;
@@ -165,6 +171,8 @@ public final class Layout {
 
     /**
      * The number of variable-length columns.
+     *
+     * @return the number of variable-length columns.
      */
     public int numVariable() {
         return this.numVariable;
@@ -172,27 +180,34 @@ public final class Layout {
 
     /**
      * Unique identifier of the schema from which this {@link Layout} was generated.
+     *
+     * @return the unique identifier of the schema from which this {@link Layout} was generated.
      */
     public SchemaId schemaId() {
         return this.schemaId;
     }
 
     /**
-     * Minimum required size of a row of this layout.
+     * The minimum required size of a row with this layout.
      * <p>
      * This size excludes all sparse columns, and assumes all columns (including variable) are
      * null.
+     *
+     * @return the minimum required size of a row with this layout.
      */
     public int size() {
         return this.size;
     }
 
     /**
-     * Returns a human readable diagnostic string representation of this {@link Layout}.
+     * A human readable diagnostic string representing this {@link Layout}.
      * <p>
      * This representation should only be used for debugging and diagnostic purposes.
+     *
+     * @return a human readable diagnostic string representing this {@link Layout}.
      */
     @Override
+    @Nonnull
     public String toString() {
 
         StringBuilder sb = new StringBuilder();
@@ -217,7 +232,9 @@ public final class Layout {
     }
 
     /**
-     * A tokenizer for path strings.
+     * A {@linkplain StringTokenizer tokenizer} for path strings.
+     *
+     * @return a {@linkplain StringTokenizer tokenizer} for path strings.
      */
     public StringTokenizer tokenizer() {
         return this.tokenizer;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutBoolean.java

@@ -135,7 +135,7 @@ public final class LayoutBoolean extends LayoutTypePrimitive<Boolean> implements
 
     @Override
     @Nonnull
-    public Result writeSparse(RowBuffer buffer, RowCursor edit, Boolean value) {
+    public Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull Boolean value) {
         return this.writeSparse(buffer, edit, value, UpdateOptions.UPSERT);
     }
 }

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCodeTraits.java

@@ -5,23 +5,25 @@ package com.azure.data.cosmos.serialization.hybridrow.layouts;
 
 public final class LayoutCodeTraits {
     /**
-     * {@code true} if the specified layout code indicates that an element type always requires a type code
+     * {@code true} if the specified layout code indicates that an element type always requires a type code.
      * <p>
      * When this method returns {@code true} it indicates that the element value is in the type code.
      *
      * @param code The element type code.
+     * @return {@code true} if the specified layout code indicates that an element type always requires a type code.
      */
     public static boolean alwaysRequiresTypeCode(LayoutCode code) {
         return (code == LayoutCode.BOOLEAN) || (code == LayoutCode.BOOLEAN_FALSE) || (code == LayoutCode.NULL);
     }
 
     /**
-     * Returns a canonicalized version of the specified layout code.
+     * A canonicalized version of the specified layout code.
      * <p>
      * 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.
+     * @return a canonicalized version of the specified layout code.
      */
     public static LayoutCode canonicalize(LayoutCode code) {
         return (code == LayoutCode.BOOLEAN_FALSE) ? LayoutCode.BOOLEAN : code;
@@ -30,7 +32,8 @@ public final class LayoutCodeTraits {
     /**
      * Returns the same scope code without the immutable bit set.
      *
-     * @param code The scope type code
+     * @param code The scope type code.
+     * @return the same scope code without the immutable bit set.
      */
     public static LayoutCode clearImmutableBit(LayoutCode code) {
         return LayoutCode.from((byte) (code.value() & 0xFE));

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutColumn.java

@@ -68,33 +68,41 @@ public final class LayoutColumn {
     }
 
     /**
-     * For bool fields, zero-based index into the bit mask for the bool value.
+     * For boolean fields, the zero-based index into the bit mask for the boolean value.
+     *
+     * @return for boolean fields, the zero-based index into the bit mask for the boolean value.
      */
     public @Nonnull LayoutBit booleanBit() {
         return this.booleanBit;
     }
 
     /**
-     * Full logical path of the field within the row
+     * Full logical path of the field within the row.
      * <p>
      * 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'.
+     *
+     * @return Full logical path of the field within the row.
      */
     public @Nonnull Utf8String fullPath() {
         return this.fullPath;
     }
 
     /**
-     * Zero-based index of the column within the structure
+     * Zero-based index of the column within the structure.
      * <p>
      * This value also indicates which presence bit controls this column.
+     *
+     * @return Zero-based index of the column within the structure.
      */
     public int index() {
         return this.index;
     }
 
     /**
-     * For nullable fields, the zero-based index into the bit mask for the null bit
+     * For nullable fields, the zero-based index into the bit mask for the null bit.
+     *
+     * @return For nullable fields, the zero-based index into the bit mask for the null bit.
      */
     public @Nonnull LayoutBit nullBit() {
         return this.nullBit;
@@ -107,13 +115,17 @@ public final class LayoutColumn {
      * beginning of the variable length segment.
      * <p>
      * For all other values of {@link #storage()}, {@code offset} is ignored.
+     *
+     * @return If {@link #storage()} equals {@link StorageKind#FIXED} then the byte offset to the field location.
      */
     public int offset() {
         return this.offset;
     }
 
     /**
-     * Layout of the parent scope, if a nested column, otherwise null.
+     * Layout of the parent scope, if a nested column, otherwise {@code null}.
+     *
+     * @return Layout of the parent scope, if a nested column, otherwise {@code null}.
      */
     public LayoutColumn parent() {
         return this.parent;
@@ -124,14 +136,19 @@ public final class LayoutColumn {
      * <p>
      * 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'.
+     *
+     * @return the relative path of the field within its parent scope.
      */
     public @Nonnull Utf8String path() {
         return this.path;
     }
 
     /**
-     * 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 boolean byte holding the value of
-     * holding the value of this type, otherwise must be 0.
+     * this type, otherwise must be 0.
+     *
+     * @return If {@link LayoutType#isBoolean()} then the zero-based extra index within the boolean byte holding the
+     * value of this type, otherwise must be 0.
      */
     public int size() {
         return this.size;
@@ -139,6 +156,8 @@ public final class LayoutColumn {
 
     /**
      * The storage kind of the field.
+     *
+     * @return the storage kind of the field.
      */
     public @Nonnull StorageKind storage() {
         return this.storage;
@@ -146,13 +165,17 @@ public final class LayoutColumn {
 
     /**
      * The physical layout type of the field.
+     *
+     * @return the physical layout type of the field.
      */
     public @Nonnull LayoutType type() {
         return this.type;
     }
 
     /**
-     * The full logical type
+     * The full logical type.
+     *
+     * @return the full logical type.
      */
     public @Nonnull TypeArgument typeArg() {
         return this.typeArg;
@@ -160,6 +183,8 @@ public final class LayoutColumn {
 
     /**
      * For types with generic parameters (e.g. {@link LayoutTuple}, the type parameters.
+     *
+     * @return for types with generic parameters (e.g. {@link LayoutTuple}, the type parameters.
      */
     public @Nonnull TypeArgumentList typeArgs() {
         return this.typeArgs;
@@ -167,6 +192,10 @@ public final class LayoutColumn {
 
     /**
      * The physical layout type of the field cast to the specified type.
+     *
+     * @param <T> a type that implements {@code ILayoutType}.
+     *
+     * @return The physical layout type of the field cast to the specified type.
      */
     @SuppressWarnings("unchecked")
     public @Nonnull <T extends ILayoutType> T typeAs() {
@@ -184,11 +213,11 @@ public final class LayoutColumn {
     }
 
     /**
-     * Computes the full logical path to the column
+     * Computes the full logical path to the column.
      *
-     * @param parent The layout of the parent scope, if a nested column, otherwise null
+     * @param parent The layout of the parent scope, if a nested column, otherwise null.
-     * @param path   The path to the field relative to parent scope
+     * @param path   The path to the field relative to parent scope.
-     * @return The full logical path
+     * @return The full logical path.
      */
     private static @Nonnull String fullPath(final LayoutColumn parent, @Nonnull final String path) {
 

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutNull.java

@@ -34,7 +34,7 @@ public final class LayoutNull extends LayoutTypePrimitive<NullValue> implements
 
     @Override
     @Nonnull
-    public Result readFixed(RowBuffer buffer, RowCursor scope, LayoutColumn column, Out<NullValue> value) {
+    public Result readFixed(@Nonnull RowBuffer buffer, @Nonnull RowCursor scope, @Nonnull LayoutColumn column, @Nonnull Out<NullValue> value) {
         checkArgument(scope.scopeType() instanceof LayoutUDT);
         value.set(NullValue.DEFAULT);
         if (!buffer.readBit(scope.start(), column.nullBit())) {
@@ -45,7 +45,7 @@ public final class LayoutNull extends LayoutTypePrimitive<NullValue> implements
 
     @Override
     @Nonnull
-    public Result readSparse(RowBuffer buffer, RowCursor edit, Out<NullValue> value) {
+    public Result readSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull Out<NullValue> value) {
         Result result = prepareSparseRead(buffer, edit, this.layoutCode());
         if (result != Result.SUCCESS) {
             value.set(null);
@@ -57,7 +57,7 @@ public final class LayoutNull extends LayoutTypePrimitive<NullValue> implements
 
     @Override
     @Nonnull
-    public Result writeFixed(RowBuffer buffer, RowCursor scope, LayoutColumn column, NullValue value) {
+    public Result writeFixed(@Nonnull RowBuffer buffer, @Nonnull RowCursor scope, @Nonnull LayoutColumn column, @Nonnull NullValue value) {
         checkArgument(scope.scopeType() instanceof LayoutUDT);
         if (scope.immutable()) {
             return Result.INSUFFICIENT_PERMISSIONS;
@@ -68,7 +68,7 @@ public final class LayoutNull extends LayoutTypePrimitive<NullValue> implements
 
     @Override
     @Nonnull
-    public Result writeSparse(RowBuffer buffer, RowCursor edit, NullValue value, UpdateOptions options) {
+    public Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull NullValue value, @Nonnull UpdateOptions options) {
         Result result = prepareSparseWrite(buffer, edit, this.typeArg(), options);
         if (result != Result.SUCCESS) {
             return result;
@@ -79,7 +79,7 @@ public final class LayoutNull extends LayoutTypePrimitive<NullValue> implements
 
     @Override
     @Nonnull
-    public Result writeSparse(RowBuffer buffer, RowCursor edit, NullValue value) {
+    public Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull NullValue value) {
         return this.writeSparse(buffer, edit, value, UpdateOptions.UPSERT);
     }
 }

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutType.java

@@ -14,11 +14,10 @@ import javax.annotation.Nonnull;
 
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
-import static com.google.common.base.Strings.lenientFormat;
 
 /**
  * Describes the physical byte layout of a hybrid row field of a specific physical type {@code T}.
- *
+ * <p>
  * {@link LayoutType} provides methods for manipulating hybrid row fields of a particular type, and properties that
  * describe the layout of fields of that type.
  */
@@ -40,6 +39,10 @@ public abstract class LayoutType /*implements ILayoutType*/ {
 
     /**
      * Initializes a new instance of the {@link LayoutType} class.
+     *
+     * @param code      the {@linkplain LayoutCode} layout code of the instance.
+     * @param immutable {@code true} if edits to fields with this layout type are prohibited.
+     * @param size      size of fields with this layout type in bytes.
      */
     protected LayoutType(@Nonnull final LayoutCode code, final boolean immutable, final int size) {
 
@@ -55,47 +58,63 @@ public abstract class LayoutType /*implements ILayoutType*/ {
 
     /**
      * Initializes a new instance of the {@link LayoutType} class.
+     *
+     * @param code the {@linkplain LayoutCode} layout code of the instance.
+     * @param size size of fields with this layout type in bytes.
      */
     protected LayoutType(LayoutCode code, int size) {
         this(code, false, size);
     }
 
     /**
-     * True if this type is a boolean.
+     * {@code true} if this type is a boolean.
+     *
+     * @return {@code true} if this type is a boolean.
      */
     public boolean isBoolean() {
         return false;
     }
 
     /**
-     * True if this type is always fixed length.
+     * {@code true} if this type is always fixed length.
+     *
+     * @return {@code true} if this type is always fixed length.
      */
     public abstract boolean isFixed();
 
     /**
-     * If true, this edit's nested fields cannot be updated individually.
+     * {@code true} if this {@link LayoutType}'s nested fields cannot be updated individually.
-     * The entire edit can still be replaced.
+     * <p>
+     * Instances of this {@link LayoutType} can still be replaced in their entirety.
+     *
+     * @return {@code true} if this {@link LayoutType}'s nested fields cannot be updated individually.
      */
     public boolean isImmutable() {
         return this.immutable;
     }
 
     /**
-     * True if this type is a literal null.
+     * {@code true} if this type is a literal null.
+     *
+     * @return {@code true} if this type is a literal null.
      */
     public boolean isNull() {
         return false;
     }
 
     /**
-     * True if this type is a variable-length encoded integer type (either signed or unsigned).
+     * {@code true} if this type is a variable-length encoded integer type (either signed or unsigned).
+     *
+     * @return {@code true} if this type is a variable-length encoded integer type (either signed or unsigned).
      */
     public boolean isVarint() {
         return false;
     }
 
     /**
-     * True if this type can be used in the variable-length segment.
+     * {@code true} if this type can be used in the variable-length segment.
+     *
+     * @return {@code true} if this type can be used in the variable-length segment.
      */
     public final boolean allowVariable() {
         return !this.isFixed();
@@ -114,6 +133,8 @@ public abstract class LayoutType /*implements ILayoutType*/ {
 
     /**
      * The physical layout code used to represent the type within the serialization.
+     *
+     * @return the physical layout code used to represent the type within the serialization.
      */
     @Nonnull
     public LayoutCode layoutCode() {
@@ -122,6 +143,8 @@ public abstract class LayoutType /*implements ILayoutType*/ {
 
     /**
      * Human readable name of the type.
+     *
+     * @return human readable name of the type.
      */
     @Nonnull
     public abstract String name();
@@ -129,9 +152,9 @@ public abstract class LayoutType /*implements ILayoutType*/ {
     /**
      * Helper for preparing the delete of a sparse field.
      *
-     * @param buffer    The row to delete from.
+     * @param buffer The row to delete from.
-     * @param edit The parent edit containing the field to delete.
+     * @param edit   The parent edit containing the field to delete.
-     * @param code The expected type of the field.
+     * @param code   The expected type of the field.
      * @return Success if the delete is permitted, the error code otherwise.
      */
     @Nonnull
@@ -339,6 +362,8 @@ public abstract class LayoutType /*implements ILayoutType*/ {
 
     /**
      * If fixed, the fixed size of the type's serialization in bytes, otherwise undefined.
+     *
+     * @return If fixed, the fixed size of the type's serialization in bytes, otherwise undefined.
      */
     public int size() {
         return this.size;
@@ -360,10 +385,13 @@ public abstract class LayoutType /*implements ILayoutType*/ {
 
     /**
      * The physical layout type of the field cast to the specified type.
+     *
+     * @param <T> a type that implements {@link ILayoutType}.
+     * @return the physical layout type of the field cast to the specified type.
      */
     @SuppressWarnings("unchecked")
     public final <T extends ILayoutType> T typeAs() {
-        return (T)this;
+        return (T) this;
     }
 
     public int writeTypeArgument(@Nonnull final RowBuffer buffer, int offset, @Nonnull final TypeArgumentList value) {

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypePrimitive.java

@@ -17,9 +17,9 @@ public abstract class LayoutTypePrimitive<T> extends LayoutType implements ILayo
     /**
      * Initializes a new instance of the {@link LayoutTypePrimitive} class.
      *
-     * @param code
+     * @param code      the {@link LayoutCode} of this layout type.
-     * @param immutable
+     * @param immutable indicates whether edits of instances fields with this layout type are permitted.
-     * @param size
+     * @param size      the size of fields with this layout type in bytes.
      */
     protected LayoutTypePrimitive(@Nonnull LayoutCode code, boolean immutable, int size) {
         super(code, immutable, size);
@@ -28,12 +28,13 @@ public abstract class LayoutTypePrimitive<T> extends LayoutType implements ILayo
     /**
      * Initializes a new instance of the {@link LayoutTypePrimitive} class.
      *
-     * @param code
+     * @param code the {@link LayoutCode} of this layout type.
-     * @param size
+     * @param size the size of fields with this layout type in bytes.
      */
     protected LayoutTypePrimitive(LayoutCode code, int size) {
         super(code, size);
     }
+
     // TODO: DANOBLE: move methods implemented by the C# code LayoutType<T> to this type from LayoutType<T>
     // Also:
     // * Convert LayoutType<T> to a non-generic type (LayoutType, not LayoutType<T>)
@@ -81,8 +82,10 @@ public abstract class LayoutTypePrimitive<T> extends LayoutType implements ILayo
      * <p>
      * If a value exists, then it is removed.  The remainder of the row is resized to accommodate
      * a decrease in required space.  If no value exists this operation is a no-op.
-     * @param buffer
+     *
-     * @param edit
+     * @param buffer target {@link RowBuffer}.
+     * @param edit a {@link RowCursor} that identifies and locates the field to be deleted.
+     * @return {@link Result#SUCCESS} if the value was deleted; otherwise an error {@link Result}.
      */
     @Nonnull
     public final Result deleteSparse(RowBuffer buffer, RowCursor edit) {
@@ -100,8 +103,13 @@ public abstract class LayoutTypePrimitive<T> extends LayoutType implements ILayo
     /**
      * Delete an existing value.
      * <p>
-     * If a value exists, then it is removed.  The remainder of the row is resized to accommodate a decrease in
+     * If a value exists, then it is removed. The remainder of the row is resized to accommodate a decrease in required
-     * required space.  If no value exists this operation is a no-op.
+     * space. If no value exists this operation is a no-op.
+     *
+     * @param buffer the target {@link RowBuffer}.
+     * @param scope  a {@linkplain RowCursor cursor} that identifies and locates the scope of the deletion.
+     * @param column identifies and locates the value within the scope to be deleted.
+     * @return {@link Result#SUCCESS} if the value was deleted; otherwise an error {@link Result}.
      */
     @Nonnull
     public final Result deleteVariable(
@@ -159,16 +167,31 @@ public abstract class LayoutTypePrimitive<T> extends LayoutType implements ILayo
     }
 
     @Nonnull
-    public abstract Result writeFixed(@Nonnull RowBuffer buffer, @Nonnull RowCursor scope, @Nonnull LayoutColumn column, @Nonnull T value);
+    public abstract Result writeFixed(
+        @Nonnull RowBuffer buffer,
+        @Nonnull RowCursor scope,
+        @Nonnull LayoutColumn column,
+        @Nonnull T value);
 
     @Nonnull
-    public abstract Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull T value);
+    public abstract Result writeSparse(
+        @Nonnull RowBuffer buffer,
+        @Nonnull RowCursor edit,
+        @Nonnull T value);
 
     @Nonnull
-    public abstract Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull T value, @Nonnull UpdateOptions options);
+    public abstract Result writeSparse(
+        @Nonnull RowBuffer buffer,
+        @Nonnull RowCursor edit,
+        @Nonnull T value,
+        @Nonnull UpdateOptions options);
 
     @Nonnull
-    public Result writeVariable(@Nonnull RowBuffer buffer, @Nonnull RowCursor scope, @Nonnull LayoutColumn column, @Nonnull T value) {
+    public Result writeVariable(
+        @Nonnull RowBuffer buffer,
+        @Nonnull RowCursor scope,
+        @Nonnull LayoutColumn column,
+        @Nonnull T value) {
         return Result.FAILURE;
     }
 }

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypeScope.java

@@ -40,9 +40,9 @@ public abstract class LayoutTypeScope extends LayoutType {
     }
 
     /**
-     * Returns {@code false} to indicate that a {@link LayoutTypeScope} is a variable length, not fixed length layout type
+     * {@code true} if the {@link LayoutTypeScope} has a fixed-, not variable-length layout type.
      *
-     * @return {@code false}
+     * @return {@code true} if the {@link LayoutTypeScope} has a fixed-, not variable-length layout type.
      */
     @Override
     public boolean isFixed() {
@@ -50,35 +50,45 @@ public abstract class LayoutTypeScope extends LayoutType {
     }
 
     /**
-     * Returns true if this is a fixed arity scope.
+     * {@code true} if this is a fixed arity scope.
+     *
+     * @return {@code true} if this is a fixed arity scope.
      */
     public boolean isFixedArity() {
         return this.isFixedArity;
     }
 
     /**
-     * Returns true if this is an indexed scope.
+     * {@code true} if this is an indexed scope.
+     *
+     * @return {@code true} if this is an indexed scope.
      */
     public boolean isIndexedScope() {
         return this.isIndexedScope;
     }
 
     /**
-     * Returns true if this is a sized scope.
+     * {@code true} if this is a sized scope.
+     *
+     * @return {@code true} if this is a sized scope.
      */
     public boolean isSizedScope() {
         return this.isSizedScope;
     }
 
     /**
-     * Returns true if this is a typed scope.
+     * {@code true} if this is a typed scope.
+     *
+     * @return {@code true} if this is a typed scope.
      */
     public boolean isTypedScope() {
         return this.isTypedScope;
     }
 
     /**
-     * Returns true if the scope's elements cannot be updated directly.
+     * {@code true} if the scope's elements cannot be updated directly.
+     *
+     * @return {@code true} if the scope's elements cannot be updated directly.
      */
     public boolean isUniqueScope() {
         return this.isUniqueScope;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUniqueScope.java

@@ -90,15 +90,18 @@ public abstract class LayoutUniqueScope extends LayoutIndexedScope implements IL
      * @param buffer           The row to move within.
      * @param destinationScope The parent unique indexed edit into which the field should be moved.
      * @param sourceEdit       The field to be moved.
-     * @return Success if the field is permitted within the unique index, the error code otherwise.
+     * @return {@link Result#SUCCESS} if the field is moved; an error {@link Result} otherwise.
      * <p>
      * The source field MUST be a field whose type arguments match the element type of the
      * destination unique index.
-     * <para />
+     * <p>
-     * The source field is delete whether the move succeeds or fails.
+     * The source field is deleted whether the move succeeds or fails.
      */
     @Nonnull
-    public final Result moveField(RowBuffer buffer, RowCursor destinationScope, RowCursor sourceEdit) {
+    public final Result moveField(
+        @Nonnull final RowBuffer buffer,
+        @Nonnull final RowCursor destinationScope,
+        @Nonnull final RowCursor sourceEdit) {
         return this.moveField(buffer, destinationScope, sourceEdit, UpdateOptions.UPSERT);
     }
 

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/StringTokenizer.java

@@ -83,6 +83,8 @@ public final class StringTokenizer {
 
     /**
      * The number of unique tokens described by the encoding.
+     *
+     * @return the number of unique tokens described by the encoding.
      */
     public int count() {
         return this.count;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgument.java

@@ -22,7 +22,7 @@ public final class TypeArgument {
     /**
      * Initializes a new instance of the {@link TypeArgument} struct.
      *
-     * @param type The type of the constraint.
+     * @param type the type of the constraint.
      */
     public TypeArgument(@Nonnull LayoutType type) {
         checkNotNull(type, "expected non-null type");
@@ -72,6 +72,8 @@ public final class TypeArgument {
 
     /**
      * The physical layout type.
+     *
+     * @return the physical layout type.
      */
     public LayoutType type() {
         return this.type;
@@ -79,6 +81,8 @@ public final class TypeArgument {
 
     /**
      * If the type argument is itself generic, then its type arguments.
+     *
+     * @return it the type argument is itself generic, then its type arguments.
      */
     public TypeArgumentList typeArgs() {
         return this.typeArgs;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgumentList.java

@@ -30,9 +30,9 @@ public final class TypeArgumentList {
     private final SchemaId schemaId;
 
     /**
-     * Initializes a new instance of the {@link TypeArgumentList} class
+     * Initializes a new instance of the {@link TypeArgumentList} class.
      *
-     * @param args arguments in the list
+     * @param args arguments in the list.
      */
     public TypeArgumentList(@Nonnull final TypeArgument... args) {
         checkNotNull(args);
@@ -109,6 +109,8 @@ public final class TypeArgumentList {
 
     /**
      * For UDT fields, the schema id of the nested layout.
+     *
+     * @return for UDT fields, the Schema ID of the nested layout.
      */
     public SchemaId schemaId() {
         return this.schemaId;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/MapPropertyType.java

@@ -18,6 +18,8 @@ public class MapPropertyType extends ScopePropertyType {
 
     /**
      * (Optional) type of the keys of the map, if a typed map, otherwise {@code null}.
+     *
+     * @return type of the keys of the map, if a type map, otherwise {@code null}.
      */
     public final PropertyType keys() {
         return this.keys;
@@ -30,6 +32,8 @@ public class MapPropertyType extends ScopePropertyType {
 
     /**
      * (Optional) type of the values of the map, if a typed map, otherwise {@code null}.
+     *
+     * @return type of the values of the map, if a typed map, otherwise {@code null}.
      */
     public final PropertyType values() {
         return this.values;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ObjectPropertyType.java

@@ -26,6 +26,8 @@ public class ObjectPropertyType extends ScopePropertyType {
 
     /**
      * A list of zero or more property definitions that define the columns within the schema.
+     *
+     * @return a list of zero or more property definitions that define the columns within the schema.
      */
     public final List<Property> properties() {
         return this.properties;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimarySortKey.java

@@ -14,7 +14,10 @@ public class PrimarySortKey {
 
     /**
      * The logical path of the referenced property.
+     * <p>
      * Primary keys MUST refer to properties defined within the same {@link Schema}.
+     *
+     * @return the logical path of the referenced property.
      */
     public final SortDirection direction() {
         return this.direction;
@@ -27,7 +30,10 @@ public class PrimarySortKey {
 
     /**
      * The logical path of the referenced property.
+     * <p>
      * Primary keys MUST refer to properties defined within the same {@link Schema}.
+     *
+     * @return the logical path of the referenced property.
      */
     public final String path() {
         return this.path;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimitivePropertyType.java

@@ -23,6 +23,8 @@ public class PrimitivePropertyType extends PropertyType {
      * The maximum allowable length in bytes.
      * <p>
      * This annotation is only valid for non-fixed length types. A value of 0 means the maximum allowable length.
+     *
+     * @return the maximum allowable length in bytes.
      */
     public final int length() {
         return this.length;
@@ -35,6 +37,8 @@ public class PrimitivePropertyType extends PropertyType {
 
     /**
      * Storage requirements of the property.
+     *
+     * @return storage requirements of the property.
      */
     public final StorageKind storage() {
         return this.storage;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/Schema.java

@@ -138,7 +138,9 @@ public class Schema {
     }
 
     /**
-     * Schema-wide operations.
+     * Schema-wide options.
+     *
+     * @return schema-wide options.
      */
     public final SchemaOptions options() {
         return this.options;
@@ -215,6 +217,8 @@ public class Schema {
      * The unique identifier for a schema.
      * <p>
      * Identifiers must be unique within the scope of the database in which they are used.
+     *
+     * @return the unique identifier for a schema.
      */
     public final SchemaId schemaId() {
         return this.id;
@@ -226,13 +230,15 @@ public class Schema {
     }
 
     /**
-     * An (optional) list of zero or more logical paths that hold data shared by all documents with same partition key.
+     * A list of zero or more logical paths that hold data shared by all documents with same partition key.
+     * <p>
      * All paths referenced MUST map to a property within the schema.
-     * <para />
+     * <p>
      * This field is never null.
      *
-     * @return
+     * @return A list of zero or more logical paths that hold data shared by all documents with same partition key.
      */
+    @Nonnull
     public final List<StaticKey> staticKeys() {
         return this.staticKeys;
     }
@@ -256,6 +262,8 @@ public class Schema {
      * The type of this schema.
      * <p>
      * This value MUST be {@link TypeKind#SCHEMA}.
+     *
+     * @return the type of this schema.
      */
     public final TypeKind type() {
         return this.type;
@@ -268,6 +276,8 @@ public class Schema {
 
     /**
      * The version of the HybridRow Schema Definition Language used to encode this schema.
+     *
+     * @return the version of the HybridRow Schema Definition Language used to encode this schema.
      */
     public final SchemaLanguageVersion version() {
         return this.version;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaHash.java

@@ -18,7 +18,7 @@ public final class SchemaHash {
     /**
      * Computes the logical hash for a logical schema.
      *
-     * @param namespace The namespace within which <paramref name="schema" /> is defined.
+     * @param namespace The namespace within which {@code schema} is defined.
      * @param schema    The logical schema to compute the hash of.
      * @param seed      The seed to initialized the hash function.
      * @return The logical 128-bit hash as a two-tuple (low, high).

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaOptions.java

@@ -13,8 +13,11 @@ public class SchemaOptions {
     private boolean enablePropertyLevelTimestamp;
 
     /**
-     * If the is value true, then disables prefixing the system properties with a prefix __sys_
+     * {@code true} if prefixing system properties with a prefix of {@code "__sys_"} is disabled.
-     * for reserved properties owned by the store layer.
+     * <p>
+     * The system property prefix is required to distinguish properties owned by the store layer.
+     *
+     * @return {@code true} if prefixing system properties with a prefix of {@code "__sys_"} is disabled.
      */
     public final boolean disableSystemPrefix() {
         return this.disableSystemPrefix;
@@ -25,7 +28,7 @@ public class SchemaOptions {
     }
 
     /**
-     * If true then structural schema validation is enabled.
+     * {@code true} if structural schema validation is enabled.
      * <p>
      * When structural schema validation is enabled then attempting to store an unschematized
      * path in the row, or a value whose type does not conform to the type constraints defined for that
@@ -33,6 +36,8 @@ public class SchemaOptions {
      * NOT enabled, then storing an unschematized path or non-confirming value will lead to a sparse
      * column override of the path.  The value will be stored (and any existing value at that path will be
      * overwritten).  No error will be given.
+     *
+     * @return {@code true} if structural schema validation is enabled.
      */
     public final boolean disallowUnschematized() {
         return this.disallowUnschematized;
@@ -43,10 +48,13 @@ public class SchemaOptions {
     }
 
     /**
-     * If set and has the value true, then triggers behavior in the Schema that acts based on property
+     * {@code true} if behavior in the Schema that acts based on property level timestamps is triggered.
-     * level timestamps. In Cassandra, this means that new columns are added for each top level property
+     * <p>
-     * that has values of the client side timestamp. This is then used in conflict resolution to independently
+     * In Cassandra, this means that new columns are added for each top level property that has values of the client
-     * resolve each property based on the timestamp value of that property.
+     * side timestamp. This is then used in conflict resolution to independently resolve each property based on the
+     * timestamp value of that property.
+     *
+     * @return {@code true} if behavior in the Schema that acts based on property level timestamps is triggered.
      */
     public final boolean enablePropertyLevelTimestamp() {
         return this.enablePropertyLevelTimestamp;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ScopePropertyType.java

@@ -8,8 +8,11 @@ public abstract class ScopePropertyType extends PropertyType {
     private boolean immutable;
 
     /**
-     * True if the property's child elements cannot be mutated in place.
+     * {@code true} if the property's child elements cannot be mutated in place.
+     * <p>
      * Immutable properties can still be replaced in their entirety.
+     *
+     * @return {@code true} if the property's child elements cannot be mutated in place.
      */
     public final boolean immutable() {
         return this.immutable;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/StaticKey.java

@@ -14,6 +14,8 @@ public class StaticKey {
      * The logical path of the referenced property.
      * <p>
      * Static path MUST refer to properties defined within the same {@link Schema}.
+     *
+     * @return the logical path of the referenced property.
      */
     public final String path() {
         return this.path;

java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/TuplePropertyType.java

@@ -24,10 +24,9 @@ public class TuplePropertyType extends ScopePropertyType {
 
     /**
      * Types of the elements of the tuple in element order.
-     * @return
+     *
+     * @return types of the elements of the tuple in element order.
      */
-    // TODO: C# TO JAVA CONVERTER: Java annotations will not correspond to .NET attributes:
-    //ORIGINAL LINE: [JsonProperty(PropertyName = "items")] public List<PropertyType> Items
     public final List<PropertyType> items() {
         return this.items;
     }