Ensure on CI that docs build without warnings (#1132)

Closes #1122

Author: kylebarron

.github/workflows/ci.yml

@@ -42,6 +42,28 @@ jobs:
       - name: Test
         run: cargo test --all-features
 
+  docs-no-warnings:
+    name: Lint and Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: "recursive"
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      # TODO: switch back to pixi environment
+      - name: Install GEOS
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libgeos-dev
+
+      # Note: in the future expand to all crates in the workspace
+      - name: Test that docs build without warnings
+        run: cargo doc --all-features --document-private-items
+        env:
+          RUSTDOCFLAGS: "-D warnings"
+
   # This part of the old test suite from `geoarrow` used external dependencies,
   # especially GEOS, GDAL, and PROJ. Come back to this once we use these
   # dependencies from inside the refactored geoarrow-* crates.

rust/geoarrow-array/README.md

@@ -79,9 +79,9 @@ fn convert_to_point_array(array: &dyn Array, field: &Field) {
 
 You can use the [`to_array_ref`][GeoArrowArray::to_array_ref] or [`into_array_ref`][GeoArrowArray::into_array_ref] methods on [`GeoArrowArray`] to convert to an [`ArrayRef`].
 
-Alternatively, if you have a concrete GeoArrow array type, you can use [`IntoArray`] to convert to a concrete arrow array type.
+Alternatively, if you have a concrete GeoArrow array type, you can use [`IntoArray`][crate::IntoArrow] to convert to a concrete arrow array type.
 
-The easiest way today to access an arrow [`Field`] is to use [`IntoArray::ext_type`] and then call `to_field` on the result. We like to make this process simpler in the future.
+The easiest way today to access an arrow [`Field`] is to use [`IntoArray::ext_type`][crate::IntoArrow::ext_type] and then call `to_field` on the result. We like to make this process simpler in the future.
 
 ## Downcasting a GeoArrow array
 

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

@@ -341,7 +341,7 @@ impl GeometryArray {
         self.buffer_lengths().num_bytes()
     }
 
-    /// Slices this [`MixedGeometryArray`] in place.
+    /// Slice this [`GeometryArray`].
     ///
     /// # Implementation
     ///

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

@@ -72,7 +72,7 @@ impl GeometryCollectionArray {
         validity_len + self.buffer_lengths().num_bytes()
     }
 
-    /// Slices this [`GeometryCollectionArray`] in place.
+    /// Slice this [`GeometryCollectionArray`].
     ///
     /// # Implementation
     ///

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

@@ -124,7 +124,7 @@ impl LineStringArray {
         validity_len + self.buffer_lengths().num_bytes()
     }
 
-    /// Slices this [`LineStringArray`] in place.
+    /// Slice this [`LineStringArray`].
     ///
     /// # Implementation
     ///

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

@@ -392,7 +392,7 @@ impl MixedGeometryArray {
         self.buffer_lengths().num_bytes()
     }
 
-    /// Slices this [`MixedGeometryArray`] in place.
+    /// Slice this [`MixedGeometryArray`].
     ///
     /// # Implementation
     ///

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

@@ -1,6 +1,6 @@
 //! The concrete array definitions.
 //!
-//! All arrays implement the core [GeoArrowArray][crate::GeoArrowArray] trait.
+//! All arrays implement the core [GeoArrowArray] trait.
 
 mod coord;
 mod geometry;

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

@@ -156,8 +156,10 @@ impl MultiLineStringArray {
         validity_len + self.buffer_lengths().num_bytes()
     }
 
-    /// Slices this [`MultiLineStringArray`] in place.
+    /// Slice this [`MultiLineStringArray`].
+    ///
     /// # Panic
+    ///
     /// This function panics iff `offset + length > self.len()`.
     #[inline]
     pub fn slice(&self, offset: usize, length: usize) -> Self {

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

@@ -128,7 +128,7 @@ impl MultiPointArray {
         validity_len + self.buffer_lengths().num_bytes()
     }
 
-    /// Slices this [`MultiPointArray`] in place.
+    /// Slice this [`MultiPointArray`].
     ///
     /// # Implementation
     ///

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

@@ -208,7 +208,8 @@ impl MultiPolygonArray {
         validity_len + self.buffer_lengths().num_bytes()
     }
 
-    /// Slices this [`MultiPolygonArray`] in place.
+    /// Slice this [`MultiPolygonArray`].
+    ///
     /// # Panic
     /// This function panics iff `offset + length > self.len()`.
     #[inline]

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

@@ -76,7 +76,7 @@ impl PointArray {
 
     /// Access the underlying coordinate buffer
     ///
-    /// Note that some coordinates may be null, depending on the value of [`Self::nulls`]
+    /// Note that some coordinates may be null, depending on the value of [`Self::logical_nulls`]
     pub fn coords(&self) -> &CoordBuffer {
         &self.coords
     }
@@ -93,7 +93,8 @@ impl PointArray {
         validity_len + self.buffer_lengths() * dimension.size() * 8
     }
 
-    /// Slices this [`PointArray`] in place.
+    /// Slice this [`PointArray`].
+    ///
     /// # Panic
     /// This function panics iff `offset + length > self.len()`.
     #[inline]

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

@@ -160,7 +160,8 @@ impl PolygonArray {
         validity_len + self.buffer_lengths().num_bytes()
     }
 
-    /// Slices this [`PolygonArray`] in place.
+    /// Slice this [`PolygonArray`].
+    ///
     /// # Panic
     /// This function panics iff `offset + length > self.len()`.
     #[inline]

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

@@ -57,19 +57,22 @@ impl RectArray {
 
     /// Access the coordinate buffer of the "lower" corner of the RectArray
     ///
-    /// Note that this needs to be interpreted in conjunction with the [null buffer][Self::nulls].
+    /// Note that this needs to be interpreted in conjunction with the [null
+    /// buffer][Self::logical_nulls].
     pub fn lower(&self) -> &SeparatedCoordBuffer {
         &self.lower
     }
 
     /// Access the coordinate buffer of the "upper" corner of the RectArray
     ///
-    /// Note that this needs to be interpreted in conjunction with the [null buffer][Self::nulls].
+    /// Note that this needs to be interpreted in conjunction with the [null
+    /// buffer][Self::logical_nulls].
     pub fn upper(&self) -> &SeparatedCoordBuffer {
         &self.upper
     }
 
-    /// Slices this [`RectArray`] in place.
+    /// Slice this [`RectArray`].
+    ///
     /// # Panic
     /// This function panics iff `offset + length > self.len()`.
     #[inline]

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

@@ -63,7 +63,9 @@ impl<O: OffsetSizeTrait> GenericWkbArray<O> {
         validity_len + self.buffer_lengths().num_bytes::<O>()
     }
 
-    /// Slices this [`GenericWkbArray`] in place.
+    /// Slice this [`GenericWkbArray`].
+    ///
+    ///
     /// # Panic
     /// This function panics iff `offset + length > self.len()`.
     #[inline]
@@ -78,7 +80,7 @@ impl<O: OffsetSizeTrait> GenericWkbArray<O> {
         }
     }
 
-    /// Replace the [ArrayMetadata] in the array with the given metadata
+    /// Replace the [Metadata] in the array with the given metadata
     pub fn with_metadata(&self, metadata: Arc<Metadata>) -> Self {
         let mut arr = self.clone();
         arr.data_type = self.data_type.clone().with_metadata(metadata);

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

@@ -38,7 +38,9 @@ impl WkbViewArray {
         self.len() == 0
     }
 
-    /// Slices this [`GenericWkbArray`] in place.
+    /// Slice this [`GenericWkbArray`].
+    ///
+    ///
     /// # Panic
     /// This function panics iff `offset + length > self.len()`.
     #[inline]
@@ -53,7 +55,7 @@ impl WkbViewArray {
         }
     }
 
-    /// Replace the [ArrayMetadata] in the array with the given metadata
+    /// Replace the [Metadata] in the array with the given metadata
     pub fn with_metadata(&self, metadata: Arc<Metadata>) -> Self {
         let mut arr = self.clone();
         arr.data_type = self.data_type.clone().with_metadata(metadata);

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

@@ -50,7 +50,8 @@ impl<O: OffsetSizeTrait> GenericWktArray<O> {
         &self.array
     }
 
-    /// Slices this [`GenericWkbArray`] in place.
+    /// Slice this [`GenericWktArray`].
+    ///
     /// # Panic
     /// This function panics iff `offset + length > self.len()`.
     #[inline]
@@ -65,7 +66,7 @@ impl<O: OffsetSizeTrait> GenericWktArray<O> {
         }
     }
 
-    /// Replace the [`ArrayMetadata`] contained in this array.
+    /// Replace the [`Metadata`] contained in this array.
     pub fn with_metadata(&self, metadata: Arc<Metadata>) -> Self {
         let mut arr = self.clone();
         arr.data_type = self.data_type.clone().with_metadata(metadata);

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

@@ -44,7 +44,9 @@ impl WktViewArray {
         &self.array
     }
 
-    /// Slices this [`WktViewArray`] in place.
+    /// Slice this [`WktViewArray`].
+    ///
+    ///
     /// # Panic
     /// This function panics iff `offset + length > self.len()`.
     #[inline]
@@ -59,7 +61,7 @@ impl WktViewArray {
         }
     }
 
-    /// Replace the [ArrayMetadata] in the array with the given metadata
+    /// Replace the [Metadata] in the array with the given metadata
     pub fn with_metadata(&self, metadata: Arc<Metadata>) -> Self {
         let mut arr = self.clone();
         arr.data_type = self.data_type.clone().with_metadata(metadata);

rust/geoarrow-array/src/builder/offsets.rs

@@ -22,13 +22,14 @@ impl<O: OffsetSizeTrait> Default for OffsetsBuilder<O> {
 }
 
 impl<O: OffsetSizeTrait> OffsetsBuilder<O> {
-    /// Returns an empty [`Offsets`] (i.e. with a single element, the zero)
+    /// Returns an empty [`OffsetsBuilder`] (i.e. with a single element, the zero)
     #[inline]
     pub(crate) fn new() -> Self {
         Self(vec![O::zero()])
     }
 
-    /// Returns a new [`Offsets`] with a capacity, allocating at least `capacity + 1` entries.
+    /// Returns a new [`OffsetsBuilder`] with a capacity, allocating at least `capacity + 1`
+    /// entries.
     pub(crate) fn with_capacity(capacity: usize) -> Self {
         let mut offsets = Vec::with_capacity(capacity + 1);
         offsets.push(O::zero());

rust/geoarrow-array/src/datatypes.rs

@@ -17,7 +17,7 @@ use crate::error::{GeoArrowError, Result};
 /// "serialized" encodings.
 ///
 /// This is designed to aid in downcasting from dynamically-typed geometry arrays in combination
-/// with the [`AsGeoArrowArray`][crate::AsGeoArrowArray] trait.
+/// with the [`AsGeoArrowArray`][crate::cast::AsGeoArrowArray] trait.
 ///
 /// This type uniquely identifies the physical buffer layout of each geometry array type.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]

rust/geoarrow-array/src/geozero/export/scalar/point.rs

@@ -18,7 +18,7 @@ pub(crate) fn process_point<P: GeomProcessor>(
 /// Note that this does _not_ call `processor.point_begin` and `processor.point_end` because as of
 /// geozero v0.12, `point_begin` and `point_end` are **not** called for each point in a
 /// MultiPoint
-/// https://github.com/georust/geozero/pull/183/files#diff-a583e23825ff28368eabfdbfdc362c6512e42097024d548fb18d88409feba76aR142-R143
+/// <https://github.com/georust/geozero/pull/183/files#diff-a583e23825ff28368eabfdbfdc362c6512e42097024d548fb18d88409feba76aR142-R143>
 pub(crate) fn process_point_as_coord<P: GeomProcessor>(
     geom: &impl PointTrait<T = f64>,
     coord_idx: usize,

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

@@ -7,7 +7,7 @@
 //! [`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.
+//! the scalar from the [`GeoArrowArrayAccessor`][crate::GeoArrowArrayAccessor] 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

rust/geoarrow-array/src/trait_.rs

@@ -35,11 +35,12 @@ pub trait IntoArrow {
 
 /// A base trait for all GeoArrow arrays.
 ///
-/// This is a geospatial corollary to the upstream [`Array`][arrow_array::Array] trait.
+/// This is a geospatial corollary to the upstream [`Array`] trait.
 pub trait GeoArrowArray: Debug + Send + Sync {
     /// Returns the array as [`Any`] so that it can be downcasted to a specific implementation.
     ///
-    /// Prefer using [`AsGeoArrowArray`] instead of calling this method and manually downcasting.
+    /// Prefer using [`AsGeoArrowArray`][crate::cast::AsGeoArrowArray] instead of calling this
+    /// method and manually downcasting.
     fn as_any(&self) -> &dyn Any;
 
     /// Returns the [`GeoArrowType`] of this array.
@@ -150,9 +151,10 @@ pub trait GeoArrowArray: Debug + Send + Sync {
     /// physical arrow representation.
     ///
     /// For most array types, this is equivalent to the "physical" nulls returned by
-    /// [`Array::nulls`]. However it is different for union arrays, including our [`GeometryArray`]
-    /// and [`GeometryCollectionArray`] types, because the unions aren't encoded in a single null
-    /// buffer.
+    /// [`Array::nulls`]. However it is different for union arrays, including our
+    /// [`GeometryArray`][crate::array::GeometryArray] and
+    /// [`GeometryCollectionArray`][crate::array::GeometryCollectionArray] types, because the
+    /// unions aren't encoded in a single null buffer.
     fn logical_nulls(&self) -> Option<NullBuffer>;
 
     /// Returns the number of null slots in this array.
@@ -417,11 +419,6 @@ pub trait GeoArrowArrayAccessor<'a>: GeoArrowArray {
 
 /// A trait describing a mutable geometry array; i.e. an array whose values can be changed.
 ///
-/// Mutable arrays cannot be cloned but can be mutated in place,
-/// thereby making them useful to perform numeric operations without allocations.
-/// As in [`NativeArray`], concrete arrays (such as
-/// [`PointBuilder`][crate::array::PointBuilder]) implement how they are mutated.
-//
 // Note: This trait is not yet publicly exported from this crate, as we're not sure how the API
 // should be, and in particular whether we need this trait to be dyn-compatible or not.
 pub(crate) trait GeoArrowArrayBuilder: Debug + Send + Sync {

rust/geoarrow-geoparquet/src/metadata.rs

@@ -159,7 +159,7 @@ impl GeoParquetGeometryType {
 ///
 /// Note: we use [`SerializeDisplay`] and [`DeserializeFromStr`] for serde because the GeoParquet
 /// spec says this concept is a single string with the dimension stored as a suffix.
-/// https://docs.rs/serde_with/3.12.0/serde_with/struct.DisplayFromStr.html
+/// <https://docs.rs/serde_with/3.12.0/serde_with/struct.DisplayFromStr.html>
 #[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, SerializeDisplay, DeserializeFromStr)]
 pub struct GeoParquetGeometryTypeAndDimension {
     geometry_type: GeoParquetGeometryType,

rust/geoarrow-geoparquet/src/reader/builder.rs

@@ -20,7 +20,7 @@ pub trait GeoParquetReaderBuilder: Sized {
 
 /// A synchronous builder used to construct [`GeoParquetRecordBatchReader`] for a file.
 ///
-/// For an async API see [`crate::io::parquet::GeoParquetRecordBatchStreamBuilder`]
+/// For an async API see [`crate::reader::GeoParquetRecordBatchStreamBuilder`]
 pub struct GeoParquetRecordBatchReaderBuilder<T: ChunkReader + 'static> {
     builder: ParquetRecordBatchReaderBuilder<T>,
     geo_meta: Option<GeoParquetMetadata>,

rust/geoarrow-geoparquet/src/reader/options.rs

@@ -59,7 +59,7 @@ impl Default for GeoParquetReaderOptions {
 }
 
 impl GeoParquetReaderOptions {
-    /// Set the size of [RecordBatch][arrow::array::RecordBatch] to produce.
+    /// Set the size of [RecordBatch][arrow_array::RecordBatch] to produce.
     ///
     /// Defaults to 1024. If the batch_size more than the file row count, use the file row count.
     pub fn with_batch_size(self, batch_size: usize) -> Self {
@@ -93,7 +93,7 @@ impl GeoParquetReaderOptions {
     /// allowing it to limit the final set of rows decoded after any pushed down predicates
     ///
     /// It is recommended to enable reading the page index if using this functionality, to allow
-    /// more efficient skipping over data pages. See [`ArrowReaderOptions::with_page_index`]
+    /// more efficient skipping over data pages. See `ArrowReaderOptions::with_page_index`
     pub fn with_limit(self, limit: usize) -> Self {
         Self {
             limit: Some(limit),

rust/geoarrow-schema/src/metadata.rs

@@ -7,9 +7,6 @@ use crate::{Crs, Edges};
 ///
 /// This follows the extension metadata [defined by the GeoArrow
 /// specification](https://geoarrow.org/extension-types).
-///
-/// This is serialized to JSON when a [`geoarrow`](self) array is exported to an [`arrow`] array
-/// and deserialized when imported from an [`arrow`] array.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
 pub struct Metadata {
     // Raise the underlying crs fields to this level.

rust/geoarrow-test/src/raw/mod.rs

@@ -1,7 +1,7 @@
 //! Raw test data, copied from geoarrow-data
 //!
-//! - https://github.com/geoarrow/geoarrow-data/blob/3feaaa0b56758e2b5d7afc1c44c6555cb589d295/example/example_src.yaml
-//! - https://github.com/geoarrow/geoarrow-data/blob/3feaaa0b56758e2b5d7afc1c44c6555cb589d295/example/example_src_generated.yaml
+//! - <https://github.com/geoarrow/geoarrow-data/blob/3feaaa0b56758e2b5d7afc1c44c6555cb589d295/example/example_src.yaml>
+//! - <https://github.com/geoarrow/geoarrow-data/blob/3feaaa0b56758e2b5d7afc1c44c6555cb589d295/example/example_src_generated.yaml>
 
 pub mod geometry;
 pub mod geometrycollection;