minor: add a diagram to docstring for DictionaryArray (#1909)

* minor: add a diagram to docstring for DictionaryArray

* minor: clarify docstring on `DictionaryArray::lookup_key`

* Apply suggestions from code review

Co-authored-by: Ruihang Xia <[email protected]>
Co-authored-by: Jörn Horstmann <[email protected]>

* make values smaller and keys larger

Co-authored-by: Wakahisa <[email protected]>
Co-authored-by: Ruihang Xia <[email protected]>
Co-authored-by: Jörn Horstmann <[email protected]>

arrow/src/array/array_dictionary.rs

@@ -33,6 +33,34 @@ use crate::error::Result;
 /// This is mostly used to represent strings or a limited set of primitive types as integers,
 /// for example when doing NLP analysis or representing chromosomes by name.
 ///
+/// [`DictionaryArray`] are represented using a `keys` array and a
+/// `values` array, which may be different lengths. The `keys` array
+/// stores indexes in the `values` array which holds
+/// the corresponding logical value, as shown here:
+///
+/// ```text
+/// ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+///   ┌─────────────────┐  ┌─────────┐ │     ┌─────────────────┐
+/// │ │        A        │  │    0    │       │        A        │     values[keys[0]]
+///   ├─────────────────┤  ├─────────┤ │     ├─────────────────┤
+/// │ │        D        │  │    2    │       │        B        │     values[keys[1]]
+///   ├─────────────────┤  ├─────────┤ │     ├─────────────────┤
+/// │ │        B        │  │    2    │       │        B        │     values[keys[2]]
+///   └─────────────────┘  ├─────────┤ │     ├─────────────────┤
+/// │                      │    1    │       │        D        │     values[keys[3]]
+///                        ├─────────┤ │     ├─────────────────┤
+/// │                      │    1    │       │        D        │     values[keys[4]]
+///                        ├─────────┤ │     ├─────────────────┤
+/// │                      │    0    │       │        A        │     values[keys[5]]
+///                        └─────────┘ │     └─────────────────┘
+/// │       values            keys
+///  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
+///                                             Logical array
+///                                                Contents
+///           DictionaryArray
+///              length = 6
+/// ```
+///
 /// Example **with nullable** data:
 ///
 /// ```