Improve PayloadConverter javadoc regarding providing of EncodingKeys#METADATA_ENCODING_KEY (#702)

Co-authored-by: Spencer Judge <sjudge@hey.com>

Author: Spikhalskiy

temporal-sdk/src/main/java/io/temporal/common/converter/EncodingKeys.java

@@ -22,8 +22,8 @@
 import com.google.protobuf.ByteString;
 import java.nio.charset.StandardCharsets;
 
-class EncodingKeys {
-  static final String METADATA_ENCODING_KEY = "encoding";
+public class EncodingKeys {
+  public static final String METADATA_ENCODING_KEY = "encoding";
 
   static final String METADATA_ENCODING_NULL_NAME = "binary/null";
   static final ByteString METADATA_ENCODING_NULL =

temporal-sdk/src/main/java/io/temporal/common/converter/PayloadConverter.java

@@ -19,6 +19,7 @@
 
 package io.temporal.common.converter;
 
+import com.google.protobuf.ByteString;
 import io.temporal.api.common.v1.Payload;
 import java.lang.reflect.Type;
 import java.util.Optional;
@@ -31,6 +32,15 @@
  */
 public interface PayloadConverter {
 
+  /**
+   * Each {@link PayloadConverter} has an Encoding Type that it handles. Each {@link
+   * PayloadConverter} should add the information about its Encoding Type into the {@link Payload} it
+   * produces inside {@link #toData(Object)} by associating it with the {@link
+   * EncodingKeys#METADATA_ENCODING_KEY} key attached to the {@code Payload}'s Metadata using {@link
+   * Payload.Builder#putMetadata(String, ByteString)}.
+   *
+   * @return encoding type that this converter handles.
+   */
   String getEncodingType();
 
   /**
@@ -40,6 +50,7 @@ public interface PayloadConverter {
    * @return converted value
    * @throws DataConverterException if conversion of the value passed as parameter failed for any
    *     reason.
+   * @see #getEncodingType() getEncodingType javadoc for an important implementation detail
    */
   Optional<Payload> toData(Object value) throws DataConverterException;
 

temporal-sdk/src/main/java/io/temporal/internal/common/HeaderUtils.java

@@ -41,7 +41,7 @@ public static Header toHeaderGrpc(
   }
 
   /**
-   * Converts a Map<String, Object> into a Map<String, Payload> by applying specified converter on
+   * Converts a {@code Map<String, Object>} into a {@code Map<String, Payload>} by applying specified converter on
    * each value. This util should be used for things like search attributes and memo that need to be
    * converted back from bytes on the server.
    */

temporal-sdk/src/main/java/io/temporal/workflow/Workflow.java

@@ -630,7 +630,7 @@ public static <T> Object getMemo(String key, Class<T> valueClass) {
   /**
    * Extract Memo associated with the given key and deserialized into an object of generic type as
    * is done here: {@link DataConverter#fromPayloads(int, java.util.Optional, java.lang.Class,
-   * java.lang.reflect.Type)} Ex: To deserialize into HashMap<String, Integer> <code>
+   * java.lang.reflect.Type)} Ex: To deserialize into {@code HashMap<String, Integer>} <code>
    *  Workflow.getMemo(key, Map.class, new TypeToken<HashMap<String, Integer>>() {}.getType());
    * </code>
    *