Restore ignored doctests (#1128)

Closes #1117, closes
#1116

Some other various docs updates.

Author: kylebarron

rust/geoarrow-array/src/array/mixed.rs

@@ -60,12 +60,10 @@ use crate::trait_::GeoArrowArray;
 /// - 37: GeometryCollection ZM
 #[derive(Debug, Clone)]
 pub struct MixedGeometryArray {
-    // We store the coord type and dimension separately because there's no NativeType::Mixed
-    // variant
     pub(crate) coord_type: CoordType,
     pub(crate) dim: Dimension,
 
-    /// Invariant: every item in `type_ids` is `> 0 && < fields.len()` if `type_ids` are not provided. If `type_ids` exist in the NativeType, then every item in `type_ids` is `> 0 && `
+    /// Invariant: every item in `type_ids` is `> 0 && < fields.len()` if `type_ids` are not provided.
     pub(crate) type_ids: ScalarBuffer<i8>,
 
     /// Invariant: `offsets.len() == type_ids.len()`
@@ -496,7 +494,7 @@ impl MixedGeometryArray {
             }
             6 => Geometry::MultiPolygon(self.multi_polygons.value(offset).expect(expect_msg)),
             7 => {
-                panic!("nested geometry collections not supported")
+                panic!("nested geometry collections not supported in GeoArrow")
             }
             _ => panic!("unknown type_id {}", type_id),
         }

rust/geoarrow-array/src/array/wkb.rs

@@ -19,9 +19,10 @@ use crate::util::{offsets_buffer_i32_to_i64, offsets_buffer_i64_to_i32};
 
 /// An immutable array of WKB geometries.
 ///
-/// This is semantically equivalent to `Vec<Option<Wkb>>` due to the internal validity bitmap.
+/// This is stored either as an Arrow [`BinaryArray`] or [`LargeBinaryArray`] and is semantically
+/// equivalent to `Vec<Option<Wkb>>` due to the internal validity bitmap.
 ///
-/// This is stored either as an Arrow [`BinaryArray`] or [`LargeBinaryArray`].
+/// Refer to [`crate::cast`] for converting this array to other GeoArrow array types.
 #[derive(Debug, Clone, PartialEq)]
 pub struct GenericWkbArray<O: OffsetSizeTrait> {
     pub(crate) data_type: WkbType,

rust/geoarrow-array/src/array/wkb_view.rs

@@ -14,9 +14,10 @@ use crate::{GeoArrowArray, GeoArrowArrayAccessor, GeoArrowType, IntoArrow};
 
 /// An immutable array of WKB geometries.
 ///
-/// This is semantically equivalent to `Vec<Option<Wkb>>` due to the internal validity bitmap.
+/// This is stored as an Arrow [`BinaryViewArray`] and is semantically equivalent to
+/// `Vec<Option<Wkb>>` due to the internal validity bitmap.
 ///
-/// This is stored as an Arrow [`BinaryViewArray`]
+/// Refer to [`crate::cast`] for converting this array to other GeoArrow array types.
 #[derive(Debug, Clone, PartialEq)]
 pub struct WkbViewArray {
     pub(crate) data_type: WkbType,

rust/geoarrow-array/src/array/wkt.rs

@@ -20,12 +20,10 @@ use crate::util::{offsets_buffer_i32_to_i64, offsets_buffer_i64_to_i32};
 
 /// An immutable array of WKT geometries using GeoArrow's in-memory representation.
 ///
-/// This is semantically equivalent to `Vec<Option<WKT>>` due to the internal validity bitmap.
+/// This is a wrapper around an Arrow [GenericStringArray] and is semantically equivalent to
+/// `Vec<Option<WKT>>` due to the internal validity bitmap.
 ///
-/// This is a wrapper around an Arrow [GenericStringArray], but additionally stores an
-/// [ArrayMetadata] so that we can persist CRS information about the data.
-///
-/// Refer to [`crate::io::wkt`] for encoding and decoding this array to the native array types.
+/// Refer to [`crate::cast`] for converting this array to other GeoArrow array types.
 #[derive(Debug, Clone, PartialEq)]
 pub struct GenericWktArray<O: OffsetSizeTrait> {
     pub(crate) data_type: WktType,

rust/geoarrow-array/src/array/wkt_view.rs

@@ -15,9 +15,10 @@ use crate::{GeoArrowArray, GeoArrowArrayAccessor, GeoArrowType, IntoArrow};
 
 /// An immutable array of WKT geometries.
 ///
-/// This is semantically equivalent to `Vec<Option<Wkt>>` due to the internal validity bitmap.
+/// This is stored as an Arrow [`StringViewArray`] and is semantically equivalent to
+/// `Vec<Option<Wkt>>` due to the internal validity bitmap.
 ///
-/// This is stored as an Arrow [`StringViewArray`].
+/// Refer to [`crate::cast`] for converting this array to other GeoArrow array types.
 #[derive(Debug, Clone, PartialEq)]
 pub struct WktViewArray {
     pub(crate) data_type: WktType,

rust/geoarrow-array/src/cast.rs

@@ -1,4 +1,5 @@
-//! Helper functions for downcasting [`dyn GeoArrowArray`][GeoArrowArray] to concrete types.
+//! Helper functions for downcasting [`dyn GeoArrowArray`][GeoArrowArray] to concrete types and for
+//! converting between GeoArrow array representations.
 
 use std::sync::Arc;
 
@@ -303,7 +304,7 @@ impl AsGeoArrowArray for Arc<dyn GeoArrowArray> {
     }
 }
 
-/// Convert a [GeoArrowArray] to a [GenericWkbArray].
+/// Convert a [GeoArrowArray] to a [`GenericWkbArray`].
 pub fn to_wkb<O: OffsetSizeTrait>(arr: &dyn GeoArrowArray) -> Result<GenericWkbArray<O>> {
     use GeoArrowType::*;
     match arr.data_type() {
@@ -371,7 +372,7 @@ fn impl_to_wkb<'a, O: OffsetSizeTrait>(
     Ok(WkbBuilder::from_nullable_geometries(geoms.as_slice(), wkb_type).finish())
 }
 
-/// Convert a [GeoArrowArray] to a [WkbViewArray].
+/// Convert a [GeoArrowArray] to a [`WkbViewArray`].
 pub fn to_wkb_view(arr: &dyn GeoArrowArray) -> Result<WkbViewArray> {
     use GeoArrowType::*;
     match arr.data_type() {
@@ -417,7 +418,8 @@ fn impl_to_wkb_view<'a>(geo_arr: &'a impl GeoArrowArrayAccessor<'a>) -> Result<W
     ))
 }
 
-/// Parse a [GenericWkbArray] to a [GeoArrowArray] with the designated [GeoArrowType].
+/// Parse a [`GenericWkbArray`] or [`WkbViewArray`] to a [`GeoArrowArray`] with the designated
+/// [`GeoArrowType`].
 ///
 /// Note that the GeoArrow metadata on the new array is taken from `to_type` **not** the original
 /// array. Ensure you construct the [GeoArrowType] with the correct metadata.
@@ -493,7 +495,7 @@ pub fn from_wkb<'a, A: GenericWkbArrayType<'a>>(
     Ok(result)
 }
 
-/// Convert a [GeoArrowArray] to a [GenericWktArray].
+/// Convert a [GeoArrowArray] to a [`GenericWktArray`].
 pub fn to_wkt<O: OffsetSizeTrait>(arr: &dyn GeoArrowArray) -> Result<GenericWktArray<O>> {
     use GeoArrowType::*;
     match arr.data_type() {
@@ -559,7 +561,7 @@ fn impl_to_wkt<'a, O: OffsetSizeTrait>(
     Ok(GenericWktArray::new(builder.finish(), metadata))
 }
 
-/// Convert a [GeoArrowArray] to a [WktViewArray].
+/// Convert a [GeoArrowArray] to a [`WktViewArray`].
 pub fn to_wkt_view(arr: &dyn GeoArrowArray) -> Result<WktViewArray> {
     use GeoArrowType::*;
     match arr.data_type() {
@@ -598,7 +600,8 @@ fn impl_to_wkt_view<'a>(geo_arr: &'a impl GeoArrowArrayAccessor<'a>) -> Result<W
     Ok(WktViewArray::new(builder.finish(), metadata))
 }
 
-/// Parse a [GenericWktArray] to a [GeoArrowArray] with the designated [GeoArrowType].
+/// Parse a [`GenericWktArray`] or [`WktViewArray`] to a [`GeoArrowArray`] with the designated
+/// [`GeoArrowType`].
 ///
 /// Note that the GeoArrow metadata on the new array is taken from `to_type` **not** the original
 /// array. Ensure you construct the [GeoArrowType] with the correct metadata.

rust/geoarrow-array/src/datatypes.rs

@@ -96,9 +96,7 @@ impl GeoArrowType {
 
     /// Get the [`Dimension`] of this data type, if it has one.
     ///
-    /// "Unknown" native arrays can hold all dimensions.
-    ///
-    /// WKB and WKT arrays will return `None`.
+    /// [`GeometryArray``], WKB and WKT arrays will return `None`.
     pub fn dimension(&self) -> Option<Dimension> {
         use GeoArrowType::*;
         match self {
@@ -140,11 +138,13 @@ impl GeoArrowType {
     ///
     /// # Examples
     ///
-    /// ```ignore
-    /// use geoarrow::{array::CoordType, datatypes::{GeoArrowType, Dimension}};
-    /// use arrow_schema::DataType;
-    ///
-    /// let data_type = GeoArrowType::Point(CoordType::Interleaved, Dimension::XY).to_data_type();
+    /// ```
+    /// # use arrow_schema::DataType;
+    /// # use geoarrow_array::GeoArrowType;
+    /// # use geoarrow_schema::{CoordType, Dimension, PointType};
+    /// #
+    /// let point_type = PointType::new(CoordType::Interleaved, Dimension::XY, Default::default());
+    /// let data_type = GeoArrowType::Point(point_type).to_data_type();
     /// assert!(matches!(data_type, DataType::FixedSizeList(_, _)));
     /// ```
     pub fn to_data_type(&self) -> DataType {
@@ -173,13 +173,15 @@ impl GeoArrowType {
     ///
     /// # Examples
     ///
-    /// ```ignore
-    /// use geoarrow::datatypes::GeoArrowType;
-    ///
-    /// let geo_data_type = GeoArrowType::Point(Default::default(), 2.try_into().unwrap());
-    /// let field = geo_data_type.to_field("geometry", false);
+    /// ```
+    /// # use geoarrow_array::GeoArrowType;
+    /// # use geoarrow_schema::{CoordType, Dimension, PointType};
+    /// #
+    /// let point_type = PointType::new(CoordType::Interleaved, Dimension::XY, Default::default());
+    /// let geoarrow_type = GeoArrowType::Point(point_type);
+    /// let field = geoarrow_type.to_field("geometry", true);
     /// assert_eq!(field.name(), "geometry");
-    /// assert!(!field.is_nullable());
+    /// assert!(field.is_nullable());
     /// assert_eq!(field.metadata()["ARROW:extension:name"], "geoarrow.point");
     /// ```
     pub fn to_field<N: Into<String>>(&self, name: N, nullable: bool) -> Field {
@@ -209,11 +211,15 @@ impl GeoArrowType {
     ///
     /// # Examples
     ///
-    /// ```ignore
-    /// use geoarrow::{array::CoordType, datatypes::GeoArrowType};
+    /// ```
+    /// # use geoarrow_array::GeoArrowType;
+    /// # use geoarrow_schema::{CoordType, Dimension, PointType};
+    /// #
+    /// let point_type = PointType::new(CoordType::Interleaved, Dimension::XY, Default::default());
+    /// let geoarrow_type = GeoArrowType::Point(point_type);
+    /// let new_type = geoarrow_type.with_coord_type(CoordType::Separated);
     ///
-    /// let geo_data_type = GeoArrowType::Point(CoordType::Interleaved, 2.try_into().unwrap());
-    /// let separated_geo_data_type = geo_data_type.with_coord_type(CoordType::Separated);
+    /// assert_eq!(new_type.coord_type(), Some(CoordType::Separated));
     /// ```
     pub fn with_coord_type(self, coord_type: CoordType) -> GeoArrowType {
         use GeoArrowType::*;
@@ -237,11 +243,15 @@ impl GeoArrowType {
     ///
     /// # Examples
     ///
-    /// ```ignore
-    /// use geoarrow::datatypes::GeoArrowType;
+    /// ```
+    /// # use geoarrow_array::GeoArrowType;
+    /// # use geoarrow_schema::{CoordType, Dimension, PointType};
+    /// #
+    /// let point_type = PointType::new(CoordType::Interleaved, Dimension::XY, Default::default());
+    /// let geoarrow_type = GeoArrowType::Point(point_type);
+    /// let new_type = geoarrow_type.with_dimension(Dimension::XYZ);
     ///
-    /// let geo_data_type = GeoArrowType::Point(Default::default(), 2.try_into().unwrap());
-    /// let geo_data_type_3d = geo_data_type.with_dimension(3.try_into().unwrap());
+    /// assert_eq!(new_type.dimension(), Some(Dimension::XYZ));
     /// ```
     pub fn with_dimension(self, dim: Dimension) -> GeoArrowType {
         use GeoArrowType::*;
@@ -357,7 +367,7 @@ impl TryFrom<&Field> for GeoArrowType {
                 },
                 name => {
                     return Err(GeoArrowError::General(format!(
-                        "Expected GeoArrow native type, got '{}'.\nIf you're passing a serialized GeoArrow type like 'geoarrow.wkb' or 'geoarrow.wkt', you need to parse to a native representation.",
+                        "Expected GeoArrow type, got '{}'.",
                         name
                     )));
                 }
@@ -392,9 +402,11 @@ impl TryFrom<&Field> for GeoArrowType {
                 },
                 DataType::Binary => Wkb(WkbType::new(metadata)),
                 DataType::LargeBinary => LargeWkb(WkbType::new(metadata)),
+                DataType::BinaryView => WkbView(WkbType::new(metadata)),
                 DataType::Utf8 => Wkt(WktType::new(metadata)),
                 DataType::LargeUtf8 => LargeWkt(WktType::new(metadata)),
-                _ => return Err(GeoArrowError::General("Only FixedSizeList, Struct, Binary, LargeBinary, String, and LargeString arrays are unambigously typed for a GeoArrow type and can be used without extension metadata.\nEnsure your array input has GeoArrow metadata.".to_string())),
+                DataType::Utf8View => WktView(WktType::new(metadata)),
+                _ => return Err(GeoArrowError::General("Only FixedSizeList, Struct, Binary, LargeBinary, BinaryView, String, LargeString, and StringView arrays are unambigously typed for a GeoArrow type and can be used without extension metadata.\nEnsure your array input has GeoArrow metadata.".to_string())),
             };
             Ok(data_type)
         }

rust/geoarrow-array/src/scalar/mod.rs

@@ -3,13 +3,16 @@
 //! For all "native" GeoArrow scalar types, (all types defined in this module) it is `O(1)` and
 //! allocation-free for any coordinate access.
 //!
-//! For "serialized" scalars emitted from the [`GenericWkbArray`][crate::array::GenericWkbArray] and
-//! [`GenericWktArray`][crate::array::GenericWktArray], there is an initial parsing step when accessing the
-//! scalar from the [`ArrayAccessor`][crate::ArrayAccessor] trait.
+//! For "serialized" scalars emitted from the [`GenericWkbArray`][crate::array::GenericWkbArray],
+//! [`WkbViewArray`][crate::array::WkbViewArray],
+//! [`GenericWktArray`][crate::array::GenericWktArray], and
+//! [`WktViewArray`][crate::array::WktViewArray], there is an initial parsing step when accessing
+//! the scalar from the [`ArrayAccessor`][crate::ArrayAccessor] trait.
 //!
 //! All scalars implement [`geo_traits`]. You can iterate through geometry parts directly using the
 //! APIs exposed by [`geo_traits`]. Or, for simplicity at the cost of a memory copy, you can use
-//! the traits defined in [`geo_traits::to_geo`] to convert these scalars to [`geo_types`] objects.
+//! the traits defined in [`geo_traits::to_geo`] to convert these scalars to [`geo_types`] objects
+//! (though keep in mind [`geo_types`] only supports 2D geometries).
 
 mod coord;
 mod geometry;