docs: improve nested type docstrings (#8358)

Co-authored-by: Phillip Cloud <417981+cpcloud@users.noreply.github.com>

ibis/expr/types/arrays.py

@@ -20,6 +20,25 @@
 
 @public
 class ArrayValue(Value):
+    """An Array is a variable-length sequence of values of a single type.
+
+    Examples
+    --------
+    >>> import ibis
+    >>> ibis.options.interactive = True
+    >>> ibis.memtable({"a": [[1, None, 3], [4], [], None]})
+    ┏━━━━━━━━━━━━━━━━━━━━━━┓
+    ┃ a                    ┃
+    ┡━━━━━━━━━━━━━━━━━━━━━━┩
+    │ array<int64>         │
+    ├──────────────────────┤
+    │ [1, None, ... +1]    │
+    │ [4]                  │
+    │ []                   │
+    │ NULL                 │
+    └──────────────────────┘
+    """
+
     def length(self) -> ir.IntegerValue:
         """Compute the length of an array.
 
@@ -1065,18 +1084,22 @@ def __getitem__(self, index: int | ir.IntegerValue | slice) -> ir.Column:
 def array(values: Iterable[V]) -> ArrayValue:
     """Create an array expression.
 
+    If any values are [column expressions](../concepts/datatypes.qmd) the
+    result will be a column. Otherwise the result will be a
+    [scalar](../concepts/datatypes.qmd).
+
     Parameters
     ----------
     values
-        An iterable of Ibis expressions or a list of Python literals
+        An iterable of Ibis expressions or Python literals
 
     Returns
     -------
     ArrayValue
 
     Examples
     --------
-    Create an array from scalar values
+    Create an array scalar from scalar values
 
     >>> import ibis
     >>> ibis.options.interactive = True

ibis/expr/types/maps.py

@@ -17,9 +17,18 @@
 
 @public
 class MapValue(Value):
-    """A map literal or column expression.
+    """A dict-like collection with fixed-type keys and values.
 
-    Can be constructed with [`ibis.map()`](#ibis.expr.types.map).
+    Maps are similar to a Python dictionary, with the restriction that all keys
+    must have the same type, and all values must have the same type.
+
+    The key type and the value type can be different.
+
+    For example, keys are `string`s, and values are `int64`s.
+
+    Keys are unique within a given map value.
+
+    Maps can be constructed with [`ibis.map()`](#ibis.expr.types.map).
 
     Examples
     --------
@@ -71,11 +80,7 @@ class MapValue(Value):
     └───────────────────┘
     """
 
-    def get(
-        self,
-        key: ir.Value,
-        default: ir.Value | None = None,
-    ) -> ir.Value:
+    def get(self, key: ir.Value, default: ir.Value | None = None) -> ir.Value:
         """Return the value for `key` from `expr`.
 
         Return `default` if `key` is not in the map.
@@ -433,11 +438,10 @@ def map(
     keys: Iterable[Any] | Mapping[Any, Any] | ArrayColumn,
     values: Iterable[Any] | ArrayColumn | None = None,
 ) -> MapValue:
-    """Create a [map container object](https://docs.python.org/3/glossary.html#term-mapping).
+    """Create a MapValue.
 
-    If the `keys` and `values` are Python literals, then the output will be a
-    `MapScalar`. If the `keys` and `values` are expressions (`ArrayColumn`),
-    then the the output will be a `MapColumn`.
+    If any of the `keys` or `values` are Columns, then the output will be a MapColumn.
+    Otherwise, the output will be a MapScalar.
 
     Parameters
     ----------
@@ -449,22 +453,19 @@ def map(
     Returns
     -------
     MapValue
-        An expression representing either a map column or literal (associative
-        array with key/value pairs of fixed types)
+        Either a MapScalar or MapColumn, depending on the input shapes.
 
     Examples
     --------
-    Create a map literal from a dict with the type inferred
+    Create a Map scalar from a dict with the type inferred
 
     >>> import ibis
     >>> ibis.options.interactive = True
     >>> ibis.map(dict(a=1, b=2))
     {'a': 1, 'b': 2}
 
-    Create a new map column from columns with keys and values
+    Create a Map Column from columns with keys and values
 
-    >>> import ibis
-    >>> ibis.options.interactive = True
     >>> t = ibis.memtable({"keys": [["a", "b"], ["b"]], "values": [[1, 2], [3]]})
     >>> t
     ┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓

ibis/expr/types/structs.py

@@ -27,55 +27,41 @@ def struct(
 ) -> StructValue:
     """Create a struct expression.
 
-    If the input expressions are all column expressions, then the output will be
-    a `StructColumn`.
-
-    If the input expressions are Python literals, then the output will be a
-    `StructScalar`.
+    If any of the inputs are Columns, then the output will be a `StructColumn`.
+    Otherwise, the output will be a `StructScalar`.
 
     Parameters
     ----------
     value
-        The underlying data for literal struct value or a pairs of field names
-        and column expressions.
+        Either a `{str: Value}` mapping, or an iterable of tuples of the form
+        `(str, Value)`.
     type
         An instance of `ibis.expr.datatypes.DataType` or a string indicating
-        the ibis type of `value`. This is only used if all of the input values
-        are literals.
+        the Ibis type of `value`. This is only used if all of the input values
+        are Python literals. eg `struct<a: float, b: string>`.
 
     Returns
     -------
     StructValue
-        An expression representing a literal or column struct (compound type with
-        fields of fixed types)
+        An StructScalar or StructColumn expression.
 
     Examples
     --------
-    Create a struct literal from a [](`dict`) with the type inferred
+    Create a struct scalar literal from a `dict` with the type inferred
+
     >>> import ibis
-    >>> t = ibis.struct(dict(a=1, b="foo"))
+    >>> ibis.options.interactive = True
+    >>> ibis.struct(dict(a=1, b="foo"))
+    {'a': 1, 'b': 'foo'}
 
-    Create a struct literal from a [](`dict`) with a specified type
-    >>> t = ibis.struct(dict(a=1, b="foo"), type="struct<a: float, b: string>")
+    Specify a type (note the 1 is now a `float`):
 
-    Specify a specific type for the struct literal
-    >>> t = ibis.struct(dict(a=1, b=40), type="struct<a: float, b: int32>")
+    >>> ibis.struct(dict(a=1, b="foo"), type="struct<a: float, b: string>")
+    {'a': 1.0, 'b': 'foo'}
 
-    Create a struct array from multiple arrays
-    >>> ibis.options.interactive = True
-    >>> t = ibis.memtable({"a": [1, 2, 3], "b": ["foo", "bar", "baz"]})
-    >>> ibis.struct([("a", t.a), ("b", t.b)])
-    ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-    ┃ StructColumn()              ┃
-    ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-    │ struct<a: int64, b: string> │
-    ├─────────────────────────────┤
-    │ {'a': 1, 'b': 'foo'}        │
-    │ {'a': 2, 'b': 'bar'}        │
-    │ {'a': 3, 'b': 'baz'}        │
-    └─────────────────────────────┘
+    Create a struct column from a column and a scalar literal
 
-    Create a struct array from columns and literals
+    >>> t = ibis.memtable({"a": [1, 2, 3]})
     >>> ibis.struct([("a", t.a), ("b", "foo")])
     ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
     ┃ StructColumn()              ┃
@@ -100,12 +86,17 @@ def struct(
 
 @public
 class StructValue(Value):
-    """A struct literal or column.
+    """A Struct is a nested type with ordered fields of any type.
+
+    For example, a Struct might have a field `a` of type `int64` and a field `b`
+    of type `string`.
 
-    Can be constructed with [`ibis.struct()`](#ibis.expr.types.struct).
+    Structs can be constructed with [`ibis.struct()`](#ibis.expr.types.struct).
 
     Examples
     --------
+    Construct a `Struct` column with fields `a: int64` and `b: string`
+
     >>> import ibis
     >>> ibis.options.interactive = True
     >>> t = ibis.memtable({"s": [{"a": 1, "b": "foo"}, {"a": 3, "b": None}, None]})
@@ -120,7 +111,8 @@ class StructValue(Value):
     │ NULL                        │
     └─────────────────────────────┘
 
-    Can use either `.` or `[]` to access fields:
+    You can use dot notation (`.`) or square-bracket syntax (`[]`) to access
+    struct column fields
 
     >>> t.s.a
     ┏━━━━━━━┓