Update javadoc and comments

Signed-off-by: sahuang <xiaohai.xu@zilliz.com>

README.md

@@ -16,6 +16,7 @@ The following table shows compatibilities between Milvus and Java SDK.
 | Milvus version | Java SDK version |
 | :------------: | :--------------: |
 |     0.11.0     |    0.9.0         |
+|     0.10.3     |    0.8.5         |
 |     0.10.2     |    0.8.4         |
 |     0.10.1     |    0.8.3         |
 |     0.10.0     |    0.8.2         |

src/main/java/io/milvus/client/CollectionMapping.java

@@ -33,6 +33,9 @@ import java.util.stream.Collectors;
 public class CollectionMapping {
   private final Mapping.Builder builder;
 
+  /**
+   * @param collectionName collection name
+   */
   public static CollectionMapping create(String collectionName) {
     return new CollectionMapping(collectionName);
   }

src/main/java/io/milvus/client/CompactParam.java

@@ -23,6 +23,7 @@ package io.milvus.client;
 public class CompactParam {
   private io.milvus.grpc.CompactParam.Builder builder;
 
+  /** @param collectionName collection to compact */
   public static CompactParam create(String collectionName) {
     return new CompactParam(collectionName);
   }
@@ -32,6 +33,12 @@ public class CompactParam {
     builder.setCollectionName(collectionName).setThreshold(0.2);
   }
 
+  /**
+   * Optional. Default to 0.2. Segment will compact if and only if the percentage of entities
+   * deleted exceeds the threshold.
+   *
+   * @param threshold The threshold
+   */
   public CompactParam setThreshold(double threshold) {
     builder.setThreshold(threshold);
     return this;

src/main/java/io/milvus/client/Index.java

@@ -33,6 +33,10 @@ import java.util.stream.Collectors;
 public class Index {
   private final IndexParam.Builder builder;
 
+  /**
+   * @param collectionName collection to create index for
+   * @param fieldName name of the field on which index is built.
+   */
   public static Index create(@Nonnull String collectionName, @Nonnull String fieldName) {
     return new Index(collectionName, fieldName);
   }
@@ -77,6 +81,7 @@ public class Index {
     return addParam("metric_type", metricType.name());
   }
 
+  /** @param paramsInJson optional parameters for index, such as <code>nlist</code> */
   public Index setParamsInJson(String paramsInJson) {
     return addParam(MilvusClient.extraParamKey, paramsInJson);
   }

src/main/java/io/milvus/client/IndexType.java

@@ -1,5 +1,6 @@
 package io.milvus.client;
 
+/** represents available index types */
 public enum IndexType {
   ANNOY,
   BIN_FLAT,

src/main/java/io/milvus/client/InsertParam.java

@@ -34,6 +34,7 @@ import java.util.stream.Collectors;
 public class InsertParam {
   private io.milvus.grpc.InsertParam.Builder builder;
 
+  /** @param collectionName collection to insert entities to */
   public static InsertParam create(String collectionName) {
     return new InsertParam(collectionName);
   }
@@ -43,11 +44,23 @@ public class InsertParam {
     builder.setCollectionName(collectionName);
   }
 
+  /**
+   * Optional. Only needed when entity ids are not auto-generated by milvus.
+   * This is specified when creating collection.
+   *
+   * @param entityIds a <code>List</code> of ids associated with the entities to insert.
+   */
   public InsertParam setEntityIds(List<Long> entityIds) {
     builder.addAllEntityIdArray(entityIds);
     return this;
   }
 
+  /**
+   * Insert into a scalar field.
+   * @param name field name
+   * @param type field DataType
+   * @param values the field values
+   */
   public <T> InsertParam addField(String name, DataType type, List<T> values) {
     AttrRecord.Builder record = AttrRecord.newBuilder();
     switch (type) {
@@ -74,6 +87,12 @@ public class InsertParam {
     return this;
   }
 
+  /**
+   * Insert into a vector field.
+   * @param name field name
+   * @param type field DataType
+   * @param values vectors
+   */
   public <T> InsertParam addVectorField(String name, DataType type, List<T> values) {
     VectorRecord.Builder record = VectorRecord.newBuilder();
     switch (type) {
@@ -100,6 +119,11 @@ public class InsertParam {
     return this;
   }
 
+  /**
+   * Optional. Default to an empty <code>String</code>
+   *
+   * @param partitionTag partition tag
+   */
   public InsertParam setPartitionTag(String partitionTag) {
     builder.setPartitionTag(partitionTag);
     return this;

src/main/java/io/milvus/client/MetricType.java

@@ -1,5 +1,6 @@
 package io.milvus.client;
 
+/** represents available metric types */
 public enum MetricType {
   HAMMING,
   IP,

src/main/java/io/milvus/client/MilvusClient.java

@@ -38,7 +38,6 @@ public interface MilvusClient {
   String clientVersion = new Supplier<String>() {
 
     @Override
-    /** @return current Milvus client version */
     public String get() {
       Properties properties = new Properties();
       try (InputStream inputStream =
@@ -54,7 +53,7 @@ public interface MilvusClient {
 
   String target();
 
-  /** @return current Milvus client version： 0.9.0 */
+  /** @return current Milvus client version */
   default String getClientVersion() {
     return clientVersion;
   }
@@ -71,6 +70,11 @@ public interface MilvusClient {
    */
   void close(long maxWaitSeconds);
 
+  /**
+   * Milvus service with timeout support.
+   * @param timeout the desired timeout
+   * @param timeoutUnit unit for timeout
+   */
   MilvusClient withTimeout(long timeout, TimeUnit timeoutUnit);
 
   /**
@@ -80,12 +84,16 @@ public interface MilvusClient {
    * <pre>
    * example usage:
    * <code>
-   * CollectionMapping collectionMapping = new CollectionMapping.Builder(collectionName)
-   *                                                            .withFields(fields)
-   *                                                            .withParamsInJson("{"segment_row_limit": 100000}")
-   *                                                            .build();
+   * CollectionMapping collectionMapping = CollectionMapping
+   *                          .create(collectionName)
+   *                          .addField("int64", DataType.INT64)
+   *                          .addVectorField("float_vec", DataType.VECTOR_FLOAT, dimension)
+   *                          .setParamsInJson(new JsonBuilder()
+   *                              .param("segment_row_limit", 50000)
+   *                              .param("auto_id", false)
+   *                              .build());
    * </code>
-   * Refer to <code>withFields</code> method for example <code>fields</code> usage.
+   * Refer to <code>addField</code> and <code>addVectorField</code> for example usage.
    * </pre>
    *
    * @see CollectionMapping
@@ -114,11 +122,10 @@ public interface MilvusClient {
    * <pre>
    * example usage:
    * <code>
-   * Index index = new Index.Builder(collectionName, fieldName)
-   *                        .withParamsInJson(
-   *                            "{"index_type": "IVF_FLAT", "metric_type": "L2",
-   *                              "params": {"nlist": 16384}}")
-   *                        .build();
+   * Index index = Index.create(collectionName, "float_vec")
+   *                    .setIndexType(IndexType.IVF_SQ8)
+   *                    .setMetricType(MetricType.L2)
+   *                    .setParamsInJson(new JsonBuilder().param("nlist", 2048).build());
    * </code>
    * </pre>
    *
@@ -133,11 +140,10 @@ public interface MilvusClient {
    * <pre>
    * example usage:
    * <code>
-   * Index index = new Index.Builder(collectionName, fieldName)
-   *                        .withParamsInJson(
-   *                            "{"index_type": "IVF_FLAT", "metric_type": "L2",
-   *                              "params\": {"nlist": 16384}}")
-   *                        .build();
+   * Index index = Index.create(collectionName, "float_vec")
+   *                    .setIndexType(IndexType.IVF_SQ8)
+   *                    .setMetricType(MetricType.L2)
+   *                    .setParamsInJson(new JsonBuilder().param("nlist", 2048).build());
    * </code>
    * </pre>
    *
@@ -187,15 +193,16 @@ public interface MilvusClient {
    * <pre>
    * example usage:
    * <code>
-   * InsertParam insertParam = new InsertParam.Builder(collectionName)
-   *                                          .withFields(fields)
-   *                                          .withEntityIds(entityIds)
-   *                                          .withPartitionTag(tag)
-   *                                          .build();
+   * InsertParam insertParam = InsertParam
+   *                    .create(collectionName)
+   *                    .addField("int64", DataType.INT64, intValues)
+   *                    .addField("float", DataType.FLOAT, floatValues)
+   *                    .addVectorField("float_vec", DataType.VECTOR_FLOAT, vectors)
+   *                    .setEntityIds(entityIds);
    * </code>
    * </pre>
    *
-   * @return a list of ids for the inserted entities
+   * @return a list of ids of the inserted entities
    * @see InsertParam
    */
   List<Long> insert(InsertParam insertParam);
@@ -207,15 +214,16 @@ public interface MilvusClient {
    * <pre>
    * example usage:
    * <code>
-   * InsertParam insertParam = new InsertParam.Builder(collectionName)
-   *                                          .withFields(fields)
-   *                                          .withEntityIds(entityIds)
-   *                                          .withPartitionTag(tag)
-   *                                          .build();
+   * InsertParam insertParam = InsertParam
+   *                    .create(collectionName)
+   *                    .addField("int64", DataType.INT64, intValues)
+   *                    .addField("float", DataType.FLOAT, floatValues)
+   *                    .addVectorField("float_vec", DataType.VECTOR_FLOAT, vectors)
+   *                    .setEntityIds(entityIds);
    * </code>
    * </pre>
    *
-   * @return a <code>ListenableFuture</code> object which holds the list of ids for the inserted entities.
+   * @return a <code>ListenableFuture</code> object which holds the list of ids of the inserted entities.
    * @see InsertParam
    * @see ListenableFuture
    */
@@ -228,11 +236,12 @@ public interface MilvusClient {
    * <pre>
    * example usage:
    * <code>
-   * SearchParam searchParam = new SearchParam.Builder(collectionName)
-   *                                          .withDSL(dslStatement)
-   *                                          .withPartitionTags(partitionTagsList)
-   *                                          .withParamsInJson("{"fields": ["B"]}")
-   *                                          .build();
+   * SearchParam searchParam = SearchParam.create(collectionName)
+   *                                      .setDSL(dsl)
+   *                                      .setPartitionTags(partitionTagsList)
+   *                                      .setParamsInJson(new JsonBuilder()
+   *                                          .param("fields", new ArrayList<>(Arrays.asList("int64", "float_vec")))
+   *                                          .build());
    * </code>
    * </pre>
    *
@@ -249,11 +258,12 @@ public interface MilvusClient {
    * <pre>
    * example usage:
    * <code>
-   * SearchParam searchParam = new SearchParam.Builder(collectionName)
-   *                                          .withDSL(dslStatement)
-   *                                          .withPartitionTags(partitionTagsList)
-   *                                          .withParamsInJson("{"fields": ["B"]}")
-   *                                          .build();
+   * SearchParam searchParam = SearchParam.create(collectionName)
+   *                                      .setDSL(dsl)
+   *                                      .setPartitionTags(partitionTagsList)
+   *                                      .setParamsInJson(new JsonBuilder()
+   *                                          .param("fields", new ArrayList<>(Arrays.asList("int64", "float_vec")))
+   *                                          .build());
    * </code>
    * </pre>
    *
@@ -332,6 +342,8 @@ public interface MilvusClient {
    * result will be returned as JSON string.
    *
    * @param collectionName collection to show info from
+   *
+   * @return collection stats
    */
   String getCollectionStats(String collectionName);
 
@@ -417,9 +429,7 @@ public interface MilvusClient {
    * <pre>
    * example usage:
    * <code>
-   * CompactParam compactParam = new CompactParam.Builder(collectionName)
-   *                                             .withThreshold(0.3)
-   *                                             .build();
+   * CompactParam compactParam = CompactParam.create(collectionName).setThreshold(0.3);
    * </code>
    * </pre>
    *
@@ -436,9 +446,7 @@ public interface MilvusClient {
    * <pre>
    * example usage:
    * <code>
-   * CompactParam compactParam = new CompactParam.Builder(collectionName)
-   *                                             .withThreshold(0.3)
-   *                                             .build();
+   * CompactParam compactParam = CompactParam.create(collectionName).setThreshold(0.3);
    * </code>
    * </pre>
    *

src/main/java/io/milvus/client/SearchResult.java

@@ -5,6 +5,7 @@ import java.util.Map;
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;
 
+/** A class that contains information from Search */
 public class SearchResult {
   private int numQueries;
   private long topK;

src/main/java/io/milvus/client/exception/ClientSideMilvusException.java

@@ -1,5 +1,6 @@
 package io.milvus.client.exception;
 
+/** Milvus exception from client side */
 public class ClientSideMilvusException extends MilvusException {
 
   public ClientSideMilvusException(String target) {

src/main/java/io/milvus/client/exception/InvalidDsl.java

@@ -1,5 +1,6 @@
 package io.milvus.client.exception;
 
+/** Milvus exception where invalid DSL is passed by client as a query */
 public class InvalidDsl extends ClientSideMilvusException {
   private String dsl;
 

src/main/java/io/milvus/client/exception/MilvusException.java

@@ -1,5 +1,6 @@
 package io.milvus.client.exception;
 
+/** General Milvus exception */
 public abstract class MilvusException extends RuntimeException {
   private String target;
   private boolean fillInStackTrace;

src/main/java/io/milvus/client/exception/ServerSideMilvusException.java

@@ -3,6 +3,7 @@ package io.milvus.client.exception;
 import io.milvus.grpc.ErrorCode;
 import io.milvus.grpc.Status;
 
+/** Milvus exception from server side */
 public class ServerSideMilvusException extends MilvusException {
   private ErrorCode errorCode;
   private String reason;

src/main/java/io/milvus/client/exception/UnsupportedDataType.java

@@ -1,5 +1,6 @@
 package io.milvus.client.exception;
 
+/** Milvus exception where unsupported DataType is used by client */
 public class UnsupportedDataType extends ClientSideMilvusException {
   public UnsupportedDataType(String message) {
     super(null, message);

src/main/java/io/milvus/client/exception/UnsupportedServerVersion.java

@@ -2,6 +2,7 @@ package io.milvus.client.exception;
 
 import io.milvus.client.MilvusClient;
 
+/** Milvus exception where client and server versions do not match */
 public class UnsupportedServerVersion extends ClientSideMilvusException {
   private String expect;
   private String actual;