KAFKA-4404; Add javadocs to document core Connect types, especially t…

…hat integer types are signed

Author: Ewen Cheslack-Postava <[email protected]>

Reviewers: Konstantine Karantasis <[email protected]>, Jason Gustafson <[email protected]>

Closes apache#2296 from ewencp/kafka-4404-document-connect-signed-integer-types

connect/api/src/main/java/org/apache/kafka/connect/data/Schema.java

@@ -44,7 +44,66 @@ public interface Schema {
      * The type of a schema. These only include the core types; logical types must be determined by checking the schema name.
      */
     enum Type {
-        INT8, INT16, INT32, INT64, FLOAT32, FLOAT64, BOOLEAN, STRING, BYTES, ARRAY, MAP, STRUCT;
+        /**
+         *  8-bit signed integer
+         *
+         *  Note that if you have an unsigned 8-bit data source, {@link Type#INT16} will be required to safely capture all valid values
+         */
+        INT8,
+        /**
+         *  16-bit signed integer
+         *
+         *  Note that if you have an unsigned 16-bit data source, {@link Type#INT32} will be required to safely capture all valid values
+         */
+        INT16,
+        /**
+         *  32-bit signed integer
+         *
+         *  Note that if you have an unsigned 32-bit data source, {@link Type#INT64} will be required to safely capture all valid values
+         */
+        INT32,
+        /**
+         *  64-bit signed integer
+         *
+         *  Note that if you have an unsigned 64-bit data source, the {@link Decimal} logical type (encoded as {@link Type#BYTES})
+         *  will be required to safely capture all valid values
+         */
+        INT64,
+        /**
+         *  32-bit IEEE 754 floating point number
+         */
+        FLOAT32,
+        /**
+         *  64-bit IEEE 754 floating point number
+         */
+        FLOAT64,
+        /**
+         * Boolean value (true or false)
+         */
+        BOOLEAN,
+        /**
+         * Character string that supports all Unicode characters.
+         *
+         * Note that this does not imply any specific encoding (e.g. UTF-8) as this is an in-memory representation.
+         */
+        STRING,
+        /**
+         * Sequence of unsigned 8-bit bytes
+         */
+        BYTES,
+        /**
+         * An ordered sequence of elements, each of which shares the same type.
+         */
+        ARRAY,
+        /**
+         * A mapping from keys to values. Both keys and values can be arbitrarily complex types, including complex types
+         * such as {@link Struct}.
+         */
+        MAP,
+        /**
+         * A structured record containing a set of named fields, each field using a fixed, independent {@link Schema}.
+         */
+        STRUCT;
 
         private String name;