Fix javadoc

Author: cindy-peng

samples/snippets/src/test/java/com/google/datastore/snippets/ConceptsTest.java renamed to com/google/datastore/snippets/ConceptsTest.java

@@ -24,29 +24,10 @@
 import static org.junit.Assert.assertNull;
 
 import com.google.cloud.Timestamp;
-import com.google.cloud.datastore.Cursor;
-import com.google.cloud.datastore.Datastore;
-import com.google.cloud.datastore.DatastoreException;
-import com.google.cloud.datastore.DatastoreOptions;
-import com.google.cloud.datastore.Entity;
-import com.google.cloud.datastore.EntityQuery;
-import com.google.cloud.datastore.FullEntity;
-import com.google.cloud.datastore.IncompleteKey;
-import com.google.cloud.datastore.Key;
-import com.google.cloud.datastore.KeyFactory;
-import com.google.cloud.datastore.KeyQuery;
-import com.google.cloud.datastore.ListValue;
-import com.google.cloud.datastore.PathElement;
-import com.google.cloud.datastore.ProjectionEntity;
-import com.google.cloud.datastore.Query;
-import com.google.cloud.datastore.QueryResults;
-import com.google.cloud.datastore.ReadOption;
-import com.google.cloud.datastore.StringValue;
-import com.google.cloud.datastore.StructuredQuery;
+import com.google.cloud.datastore.*;
 import com.google.cloud.datastore.StructuredQuery.CompositeFilter;
 import com.google.cloud.datastore.StructuredQuery.OrderBy;
 import com.google.cloud.datastore.StructuredQuery.PropertyFilter;
-import com.google.cloud.datastore.Transaction;
 import com.google.cloud.datastore.testing.LocalDatastoreHelper;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
@@ -399,6 +380,9 @@ private void setUpQueryTests() {
                 "description",
                 StringValue.newBuilder("Learn Cloud Datastore").setExcludeFromIndexes(true).build())
             .set("tag", "fun", "l", "programming", "learn")
+            .set(
+                    "vector_property",
+                    VectorValue.newBuilder(3.0, 1.0, 2.0).setExcludeFromIndexes(true).build())
             .build());
   }
 
@@ -717,6 +701,38 @@ public void testInequalitySortInvalidNotFirst() {
     assertInvalidQuery(query);
   }
 
+  @Test
+  public void testVectorSearch() {
+    setUpQueryTests();
+    VectorValue vectorValue = VectorValue.newBuilder(1.78, 2.56, 3.88).build();
+    FindNearest vectorQuery =
+            new FindNearest(
+                    "vector_property", vectorValue, FindNearest.DistanceMeasure.COSINE, 1, "distance");
+
+    Query<Entity> query = Query.newEntityQueryBuilder().setFindNearest(vectorQuery).build();
+    assertValidQuery(query);
+  }
+
+  @Test
+  public void testVectorSearchWithEmptyVector() {
+    setUpQueryTests();
+    VectorValue emptyVector = VectorValue.newBuilder().build();
+    FindNearest vectorQuery =
+            new FindNearest("vector_property", emptyVector, FindNearest.DistanceMeasure.EUCLIDEAN, 1);
+    Query<Entity> query = Query.newEntityQueryBuilder().setFindNearest(vectorQuery).build();
+    assertInvalidQuery(query);
+  }
+
+  @Test
+  public void testVectorSearchWithUnmatchedVectorSize() {
+    setUpQueryTests();
+    VectorValue vectorValue = VectorValue.newBuilder(1.78, 2.56, 3.88, 4.33).build();
+    FindNearest vectorQuery =
+            new FindNearest("vector_property", vectorValue, FindNearest.DistanceMeasure.DOT_PRODUCT, 1);
+    Query<Entity> query = Query.newEntityQueryBuilder().setFindNearest(vectorQuery).build();
+    assertInvalidQuery(query);
+  }
+
   @Test
   public void testLimit() {
     setUpQueryTests();

google-cloud-datastore/src/main/java/com/google/cloud/datastore/FindNearest.java

@@ -26,24 +26,34 @@
 
 /**
  * A query that finds the entities whose vector fields are closest to a certain query vector. Create
- * an instance of `FindNearest` with {@link Query#findNearest}.
+ * an instance of `FindNearest` with {@link Query}.
  */
 public final class FindNearest implements Serializable {
 
+  /** An indexed vector property to search upon. */
   private final String vectorProperty;
+  /** The query vector that we are searching on. */
   private final VectorValue queryVector;
+  /** The Distance Measure to use, required. */
   private final DistanceMeasure measure;
+  /** The number of nearest neighbors to return. Must be a positive integer of no more than 100. */
   private final int limit;
-  /*
-  Optional. Optional name of the field to output the result of the vector
-     * distance calculation.
+
+  /**
+   * Optional. Optional name of the field to output the result of the vector distance calculation.
    */
   private final @Nullable String distanceResultField;
+
+  /**
+   * Optional. Option to specify a threshold for which no less similar documents will be returned.
+   * The behavior of the specified `distance_measure` will affect the meaning of the distance
+   * threshold.
+   */
   private final @Nullable Double distanceThreshold;
 
   private static final long serialVersionUID = 4688656124180403551L;
 
-  /** Creates a VectorQuery */
+  /** Creates a FindNearest query. */
   public FindNearest(
       String vectorProperty,
       VectorValue queryVector,
@@ -89,10 +99,10 @@ public int hashCode() {
   }
 
   /**
-   * Returns true if this VectorQuery is equal to the provided object.
+   * Returns true if this FindNearest query is equal to the provided object.
    *
    * @param obj The object to compare against.
-   * @return Whether this VectorQuery is equal to the provided object.
+   * @return Whether this FindNearest query is equal to the provided object.
    */
   @Override
   public boolean equals(Object obj) {
@@ -179,19 +189,15 @@ protected static com.google.datastore.v1.FindNearest.DistanceMeasure toProto(
     }
   }
 
-  /**
-   * The distance measure to use when comparing vectors in a {@link FindNearest query}.
-   *
-   * @see com.google.cloud.datastore.Query#findNearest
-   */
+  /** The distance measure to use when comparing vectors in a {@link FindNearest query}. */
   public enum DistanceMeasure {
+    DISTANCE_MEASURE_UNSPECIFIED,
     /**
      * COSINE distance compares vectors based on the angle between them, which allows you to measure
      * similarity that isn't based on the vectors' magnitude. We recommend using DOT_PRODUCT with
      * unit normalized vectors instead of COSINE distance, which is mathematically equivalent with
      * better performance.
      */
-    DISTANCE_MEASURE_UNSPECIFIED,
     COSINE,
     /** Measures the EUCLIDEAN distance between the vectors. */
     EUCLIDEAN,

google-cloud-datastore/src/main/java/com/google/cloud/datastore/ValueType.java

@@ -63,7 +63,7 @@ public enum ValueType {
   /** Represents a {@link LatLng} value. */
   LAT_LNG(LatLngValue.MARSHALLER),
 
-  /** Represents a {@link Vector} value. */
+  /** Represents a {@link VectorValue} value. */
   VECTOR(VectorValue.MARSHALLER);
 
   private static final ImmutableMap<Integer, ValueType> DESCRIPTOR_TO_TYPE_MAP;