add missing comments for StreamingSerializer

apple · Jul 21, 2021 · a164ae6 · a164ae6
1 parent f5d1bb5
commit a164ae6
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 19 deletions.
diff --git a/...cetalk-serializer-api/src/main/java/io/servicetalk/serializer/api/SerializerProvider.java b/...cetalk-serializer-api/src/main/java/io/servicetalk/serializer/api/SerializerProvider.java
diff --git a/...alk-serializer-api/src/main/java/io/servicetalk/serializer/api/StreamingDeserializer.java b/...alk-serializer-api/src/main/java/io/servicetalk/serializer/api/StreamingDeserializer.java
@@ -28,8 +28,20 @@
  */
 @FunctionalInterface
 public interface StreamingDeserializer<T> {
+    /**
+     * Deserialize a {@link Publisher} of {@link Buffer} into a {@link Publisher} of {@link T}.
+     * @param serializedData the serialized stream of data represented in a {@link Publisher} of {@link Buffer}.
+     * @param allocator the {@link BufferAllocator} to use if allocation is required.
+     * @return The deserialized {@link Publisher} of {@link T}s.
+     */
     Publisher<T> deserialize(Publisher<Buffer> serializedData, BufferAllocator allocator);
 
+    /**
+     * Deserialize a {@link Iterable} of {@link Buffer} into a {@link Iterable} of {@link T}.
+     * @param serializedData the serialized stream data represented in a {@link Iterable} of {@link Buffer}.
+     * @param allocator the {@link BufferAllocator} to use if allocation is required.
+     * @return The deserialized {@link Iterable} of {@link T}s.
+     */
     default BlockingIterable<T> deserialize(Iterable<Buffer> serializedData, BufferAllocator allocator) {
         return deserialize(fromIterable(serializedData), allocator).toIterable();
     }

diff --git a/...etalk-serializer-api/src/main/java/io/servicetalk/serializer/api/StreamingSerializer.java b/...etalk-serializer-api/src/main/java/io/servicetalk/serializer/api/StreamingSerializer.java
@@ -29,12 +29,30 @@
  */
 @FunctionalInterface
 public interface StreamingSerializer<T> {
+    /**
+     * Serialize a {@link Publisher} of {@link T}s into a {@link Publisher} of {@link Buffer}.
+     * @param toSerialize the deserialized stream of data represented in a {@link Publisher} of {@link T}.
+     * @param allocator the {@link BufferAllocator} to use if allocation is required.
+     * @return the serialized stream of data represented in a {@link Publisher} of {@link Buffer}.
+     */
     Publisher<Buffer> serialize(Publisher<T> toSerialize, BufferAllocator allocator);
 
+    /**
+     * Serialize a {@link Iterable} of {@link T}s into a {@link Iterable} of {@link Buffer}.
+     * @param toSerialize the deserialized stream of data represented in a {@link Iterable} of {@link T}.
+     * @param allocator the {@link BufferAllocator} to use if allocation is required.
+     * @return the serialized stream of data represented in a {@link Iterable} of {@link Buffer}.
+     */
     default BlockingIterable<Buffer> serialize(Iterable<T> toSerialize, BufferAllocator allocator) {
         return serialize(fromIterable(toSerialize), allocator).toIterable();
     }
 
+    /**
+     * Serialize a {@link PayloadWriter} of {@link T}s into a {@link PayloadWriter} of {@link Buffer}.
+     * @param writer The {@link PayloadWriter} used to write the result of serialization to.
+     * @param allocator the {@link BufferAllocator} to use if allocation is required.
+     * @return a {@link PayloadWriter} where you can write {@link T}s to.
+     */
     default PayloadWriter<T> serialize(PayloadWriter<Buffer> writer, BufferAllocator allocator) {
         return StreamingSerializerUtils.serialize(this, writer, allocator);
     }