[flink] 02/02: [hotfix][table-common] Improve JavaDocs of GenericArrayData

[tw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

twalthr pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git

commit ee91ff67cbc58202a1df7afcdeb775bb9ddf2aeb
Author: Timo Walther <tw...@apache.org>
AuthorDate: Wed Mar 23 13:42:45 2022 +0100

    [hotfix][table-common] Improve JavaDocs of GenericArrayData
---
 .../apache/flink/table/data/GenericArrayData.java   | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/flink-table/flink-table-common/src/main/java/org/apache/flink/table/data/GenericArrayData.java b/flink-table/flink-table-common/src/main/java/org/apache/flink/table/data/GenericArrayData.java
index 841e0f7..6c69479 100644
--- a/flink-table/flink-table-common/src/main/java/org/apache/flink/table/data/GenericArrayData.java
+++ b/flink-table/flink-table-common/src/main/java/org/apache/flink/table/data/GenericArrayData.java
@@ -29,13 +29,28 @@ import java.util.Objects;
 /**
  * An internal data structure representing data of {@link ArrayType}.
  *
+ * <p>Note: All elements of this data structure must be internal data structures and must be of the
+ * same type. See {@link RowData} for more information about internal data structures.
+ *
  * <p>{@link GenericArrayData} is a generic implementation of {@link ArrayData} which wraps regular
  * Java arrays.
  *
- * <p>Note: All elements of this data structure must be internal data structures and must be of the
- * same type. See {@link RowData} for more information about internal data structures.
+ * <p>Every instance wraps a one-dimensional Java array. Non-primitive arrays can be used for
+ * representing element nullability. The Java array might be a primitive array such as {@code int[]}
+ * or an object array (i.e. instance of {@code Object[]}). Object arrays that contain boxed types
+ * (e.g. {@link Integer}) MUST be boxed arrays (i.e. {@code new Integer[]{1, 2, 3}}, not {@code new
+ * Object[]{1, 2, 3}}). For multidimensional arrays, an array of {@link GenericArrayData} MUST be
+ * passed. For example:
  *
- * <p>For non-primitive arrays, elements can contain null for representing nullability.
+ * <pre>{@code
+ * // ARRAY < ARRAY < INT NOT NULL > >
+ * new GenericArrayData(
+ *   new GenericArrayData[]{
+ *     new GenericArrayData(new int[3]),
+ *     new GenericArrayData(new int[5])
+ *   }
+ * )
+ * }</pre>
  */
 @PublicEvolving
 public final class GenericArrayData implements ArrayData {