Merge pull request #468 from weaviate/v6-write-the-docs

v6: Update README.md and write Javadoc

Author: bevzzz

README.md

@@ -43,27 +43,37 @@ private WeaviateApiException(String method, String endpoint, int statusCode, Str
     this.grpcStatusCode = null;
   }
 
+  /** Get raw error message. */
+  public String getError() {
+    return errorMessage;
+  }
+
+  /** Check if the exception originates from the gRPC transport. */
   public boolean isGPRC() {
     return source == Source.GRPC;
   }
 
+  /** Get the gRPC status code. */
   public String grpcStatusCode() {
+    if (!isGPRC()) {
+      return null;
+    }
     return grpcStatusCode.toString();
   }
 
+  /** Check if the exception originates from the HTTP transport. */
   public boolean isHTTP() {
     return source == Source.HTTP;
   }
 
+  /** Get the endpoint that the failed request was sent to. */
   public String endpoint() {
     return endpoint;
   }
 
+  /** Get the HTTP status code. */
   public Integer httpStatusCode() {
     return httpStatusCode;
   }
 
-  public String getError() {
-    return errorMessage;
-  }
 }

assets/duke-client6.png

@@ -23,16 +23,27 @@
 import io.weaviate.client6.v1.internal.ObjectBuilder;
 
 public record CollectionConfig(
+    /** Collection name. */
     @SerializedName("class") String collectionName,
+    /** Collection description. */
     @SerializedName("description") String description,
+    /** Collection properties. */
     @SerializedName("properties") List<Property> properties,
+    /** Cross-reference properties. */
     List<ReferenceProperty> references,
+    /** Vector indexes configured for this collection. */
     @SerializedName("vectorConfig") Map<String, VectorConfig> vectors,
+    /** Multi-tenantcy options. */
     @SerializedName("multiTenancyConfig") MultiTenancy multiTenancy,
+    /** Sharding configuration. */
     @SerializedName("shardingConfig") Sharding sharding,
+    /** Replication configuration. */
     @SerializedName("replicationConfig") Replication replication,
+    /** Inverted index configuration. */
     @SerializedName("invertedIndexConfig") InvertedIndex invertedIndex,
+    /** Reranker modules. */
     List<Reranker> rerankerModules,
+    /** Generative modules. */
     Generative generativeModule) {
 
   public static CollectionConfig of(String collectionName) {
@@ -100,15 +111,26 @@ public Builder(String collectionName) {
       this.collectionName = collectionName;
     }
 
+    /** Add collection description. */
     public Builder description(String description) {
       this.description = description;
       return this;
     }
 
+    /**
+     * Add collection properties.
+     *
+     * @see Property
+     */
     public Builder properties(Property... properties) {
       return properties(Arrays.asList(properties));
     }
 
+    /**
+     * Add collection properties.
+     *
+     * @see Property
+     */
     public Builder properties(List<Property> properties) {
       properties.forEach(property -> this.properties.put(property.propertyName(), property));
       return this;
@@ -118,10 +140,20 @@ private List<Property> propertyList() {
       return this.properties.values().stream().toList();
     }
 
+    /**
+     * Add cross-reference properties.
+     *
+     * @see ReferenceProperty#to
+     */
     public Builder references(ReferenceProperty... references) {
       return references(Arrays.asList(references));
     }
 
+    /**
+     * Add cross-reference properties.
+     *
+     * @see ReferenceProperty#to
+     */
     public Builder references(List<ReferenceProperty> references) {
       references.forEach(reference -> this.references.put(reference.propertyName(), reference));
       return this;
@@ -131,66 +163,83 @@ private List<ReferenceProperty> referenceList() {
       return this.references.values().stream().toList();
     }
 
+    /** Add vector index configurations. */
     public final Builder vectorConfig(Map<String, VectorConfig> vectors) {
       this.vectors.putAll(vectors);
       return this;
     }
 
+    /**
+     * Add vector index configurations.
+     *
+     * @see VectorConfig
+     */
     @SafeVarargs
     public final Builder vectorConfig(Map.Entry<String, VectorConfig>... vectors) {
       this.vectors.putAll(Map.ofEntries(vectors));
       return this;
     }
 
+    /** Configure collection's sharding. */
     public Builder sharding(Sharding sharding) {
       this.sharding = sharding;
       return this;
     }
 
+    /** Configure collection's sharding. */
     public Builder sharding(Function<Sharding.Builder, ObjectBuilder<Sharding>> fn) {
       this.sharding = Sharding.of(fn);
       return this;
     }
 
+    /** Configure multi-tenancy. */
     public Builder multiTenancy(MultiTenancy multiTenancy) {
       this.multiTenancy = multiTenancy;
       return this;
     }
 
+    /** Configure multi-tenancy. */
     public Builder multiTenancy(Function<MultiTenancy.Builder, ObjectBuilder<MultiTenancy>> fn) {
       this.multiTenancy = MultiTenancy.of(fn);
       return this;
     }
 
+    /** Configure replication. */
     public Builder replication(Replication replication) {
       this.replication = replication;
       return this;
     }
 
+    /** Configure replication. */
     public Builder replication(Function<Replication.Builder, ObjectBuilder<Replication>> fn) {
       this.replication = Replication.of(fn);
       return this;
     }
 
+    /** Change inverted index configurations. */
     public Builder invertedIndex(InvertedIndex invertedIndex) {
       this.invertedIndex = invertedIndex;
       return this;
     }
 
+    /** Change inverted index configurations. */
     public Builder invertedIndex(Function<InvertedIndex.Builder, ObjectBuilder<InvertedIndex>> fn) {
       this.invertedIndex = InvertedIndex.of(fn);
       return this;
     }
 
+    /** Add reranker modules. */
     public Builder rerankerModules(Reranker... rerankerModules) {
       return rerankerModules(Arrays.asList(rerankerModules));
     }
 
+    /** Add reranker modules. */
     public Builder rerankerModules(List<Reranker> rerankerModules) {
       this.rerankerModules.addAll(rerankerModules);
       return this;
     }
 
+    /** Add a generative module. */
     public Builder generativeModule(Generative generativeModule) {
       this.generativeModule = generativeModule;
       return this;

src/main/java/io/weaviate/client6/v1/api/WeaviateApiException.java

@@ -49,10 +49,39 @@ private CollectionHandle(CollectionHandle<PropertiesT> c, CollectionHandleDefaul
     this.tenants = c.tenants;
   }
 
+  /**
+   * Create a Paginator over the objects in this collection.
+   *
+   * <p>
+   * Usage:
+   *
+   * <pre>
+   * {@code
+   * var things = client.collections.use("Things");
+   *
+   * // In a for-loop:
+   * for (final var thing : things.paginate()) {
+   *   // ... do something for each Thing object
+   * }
+   *
+   * // As a stream
+   * things.paginate().stream()
+   *  .map(...)
+   *  .collect(...);
+   * }</pre>
+   *
+   * @return An {@link Iterable} over this collection's objects.
+   */
   public Paginator<PropertiesT> paginate() {
     return Paginator.of(this.query);
   }
 
+  /**
+   * Create a Paginator over the objects in this collection.
+   *
+   * @param fn Lambda expression for optional parameters.
+   * @return An {@link Iterable} over this collection's objects.
+   */
   public Paginator<PropertiesT> paginate(
       Function<Paginator.Builder<PropertiesT>, ObjectBuilder<Paginator<PropertiesT>>> fn) {
     return Paginator.of(this.query, fn);
@@ -68,7 +97,7 @@ public Paginator<PropertiesT> paginate(
    * collection exceeds {@link Long#MAX_VALUE} as this is unlikely to happen.
    *
    * <p>
-   * This is a shortcut for:
+   * This is a shorthand for:
    *
    * <pre>{@code
    * handle.aggregate.overAll(all -> all.includeTotalCount(true)).totalCount()
@@ -78,22 +107,30 @@ public long size() {
     return this.aggregate.overAll(all -> all.includeTotalCount(true)).totalCount();
   }
 
+  /** Default consistency level for requests. */
   public ConsistencyLevel consistencyLevel() {
     return defaults.consistencyLevel();
   }
 
+  /** Obtain a collection handle with a different consistency level. */
   public CollectionHandle<PropertiesT> withConsistencyLevel(ConsistencyLevel consistencyLevel) {
     return new CollectionHandle<>(this, CollectionHandleDefaults.of(with -> with.consistencyLevel(consistencyLevel)));
   }
 
+  /** Default tenant for requests. */
   public String tenant() {
     return defaults.tenant();
   }
 
+  /** Obtain a collection handle with a different target tenant. */
   public CollectionHandle<PropertiesT> withTenant(String tenant) {
     return new CollectionHandle<>(this, CollectionHandleDefaults.of(with -> with.tenant(tenant)));
   }
 
+  /**
+   * Obtain a collection handle with different defaults
+   * (consistency level / tenant).
+   */
   public CollectionHandle<PropertiesT> withDefaults(
       Function<CollectionHandleDefaults.Builder, ObjectBuilder<CollectionHandleDefaults>> fn) {
     return new CollectionHandle<>(this, CollectionHandleDefaults.of(fn));

src/main/java/io/weaviate/client6/v1/api/collections/CollectionConfig.java

@@ -85,23 +85,31 @@ public CompletableFuture<Long> size() {
         .thenApply(AggregateResponse::totalCount);
   }
 
+  /** Default consistency level for requests. */
   public ConsistencyLevel consistencyLevel() {
     return defaults.consistencyLevel();
   }
 
+  /** Obtain a collection handle with a different consistency level. */
   public CollectionHandleAsync<PropertiesT> withConsistencyLevel(ConsistencyLevel consistencyLevel) {
     return new CollectionHandleAsync<>(this, CollectionHandleDefaults.of(
         def -> def.consistencyLevel(consistencyLevel)));
   }
 
+  /** Default tenant for requests. */
   public String tenant() {
     return defaults.tenant();
   }
 
+  /** Obtain a collection handle with a different target tenant. */
   public CollectionHandleAsync<PropertiesT> withTenant(String tenant) {
     return new CollectionHandleAsync<>(this, CollectionHandleDefaults.of(with -> with.tenant(tenant)));
   }
 
+  /**
+   * Obtain a collection handle with different defaults
+   * (consistency level / tenant).
+   */
   public CollectionHandleAsync<PropertiesT> withDefaults(
       Function<CollectionHandleDefaults.Builder, ObjectBuilder<CollectionHandleDefaults>> fn) {
     return new CollectionHandleAsync<>(this, CollectionHandleDefaults.of(fn));

src/main/java/io/weaviate/client6/v1/api/collections/CollectionHandle.java

@@ -54,6 +54,7 @@ public CollectionHandleDefaults build() {
     }
   }
 
+  /** Serialize default values to a URL query. */
   public Map<String, Object> queryParameters() {
     if (consistencyLevel == null && tenant == null) {
       return Collections.emptyMap();

src/main/java/io/weaviate/client6/v1/api/collections/CollectionHandleAsync.java

@@ -19,6 +19,17 @@ public interface DataType {
   public static final String UUID = "uuid";
   public static final String UUID_ARRAY = "uuid[]";
 
+  /**
+   * Scalar/array types which Weaviate and WeaviateClient recognize.
+   *
+   * <p>
+   * Other data types are considered reference types, i.e. if a user creates a
+   * property with type {@code "timestamp"}, the client will count it a
+   * cross-reference to the {@code "timestamp"} collection.
+   *
+   * This is obviously wrong, so it is recommended to always create properties
+   * using {@link Property}'s factory classes.
+   */
   public static final Set<String> KNOWN_TYPES = ImmutableSet.of(
       TEXT, INT, BLOB, BOOL, DATE, UUID, NUMBER,
       TEXT_ARRAY, INT_ARRAY, NUMBER_ARRAY, BOOL_ARRAY, DATE_ARRAY, UUID_ARRAY);

src/main/java/io/weaviate/client6/v1/api/collections/CollectionHandleDefaults.java

@@ -42,10 +42,16 @@ public static Kind valueOfJson(String jsonValue) {
 
   Object _self();
 
+  /** Configure a default Cohere generative module. */
   public static Generative cohere() {
     return CohereGenerative.of();
   }
 
+  /**
+   * Configure a Cohere generative module.
+   *
+   * @param fn Lambda expression for optional parameters.
+   */
   public static Generative cohere(Function<CohereGenerative.Builder, ObjectBuilder<CohereGenerative>> fn) {
     return CohereGenerative.of(fn);
   }