Add comments for public APIs

Author: Kontinuation

rust/sedona-geo-traits-ext/src/coord.rs

@@ -21,11 +21,13 @@ use geo_types::{Coord, CoordNum};
 
 use crate::{CoordTag, GeoTraitExtWithTypeTag};
 
+/// Extension methods that bridge [`CoordTrait`] with concrete `geo-types` helpers.
 pub trait CoordTraitExt: CoordTrait + GeoTraitExtWithTypeTag<Tag = CoordTag>
 where
     <Self as CoordTrait>::T: CoordNum,
 {
     #[inline]
+    /// Converts this coordinate into the concrete [`geo_types::Coord`].
     fn geo_coord(&self) -> Coord<Self::T> {
         Coord {
             x: self.x(),

rust/sedona-geo-traits-ext/src/geometry.rs

@@ -24,42 +24,58 @@ use geo_types::*;
 use crate::*;
 
 #[allow(clippy::type_complexity)]
+/// Extension trait that augments [`geo_traits::GeometryTrait`] with Sedona's
+/// additional helpers and type tagging support.
+///
+/// The trait adds accessors that mirror the behavior of `geo-types::Geometry`
+/// while keeping the code ergonomic when working through trait objects.
+/// Implementations must also opt into [`GeoTraitExtWithTypeTag`] so geometries
+/// can be introspected using [`GeometryTag`].
 pub trait GeometryTraitExt: GeometryTrait + GeoTraitExtWithTypeTag<Tag = GeometryTag>
 where
     <Self as GeometryTrait>::T: CoordNum,
 {
+    /// Extension-aware point type exposed by this geometry.
     type PointTypeExt<'a>: 'a + PointTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Extension-aware line string type exposed by this geometry.
     type LineStringTypeExt<'a>: 'a + LineStringTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Extension-aware polygon type exposed by this geometry.
     type PolygonTypeExt<'a>: 'a + PolygonTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Extension-aware multi point type exposed by this geometry.
     type MultiPointTypeExt<'a>: 'a + MultiPointTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Extension-aware multi line string type exposed by this geometry.
     type MultiLineStringTypeExt<'a>: 'a + MultiLineStringTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Extension-aware multi polygon type exposed by this geometry.
     type MultiPolygonTypeExt<'a>: 'a + MultiPolygonTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Extension-aware triangle type exposed by this geometry.
     type TriangleTypeExt<'a>: 'a + TriangleTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Extension-aware rectangle type exposed by this geometry.
     type RectTypeExt<'a>: 'a + RectTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Extension-aware line type exposed by this geometry.
     type LineTypeExt<'a>: 'a + LineTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
@@ -74,6 +90,7 @@ where
     // we are not certain if there will be other issues caused by recursive GATs in the future. So we decided to completely get rid
     // of recursive GATs.
 
+    /// Reference type yielded when iterating over nested geometries inside a collection.
     type InnerGeometryRef<'a>: 'a + Borrow<Self>
     where
         Self: 'a;
@@ -131,6 +148,7 @@ where
 }
 
 #[derive(Debug)]
+/// Borrowed view into a concrete geometry type implementing the extension traits.
 pub enum GeometryTypeExt<'a, P, LS, Y, MP, ML, MY, R, TT, L>
 where
     P: PointTraitExt,
@@ -164,6 +182,9 @@ where
 }
 
 #[macro_export]
+/// Forwards [`GeometryTraitExt`] associated types and methods to the
+/// underlying [`geo_traits::GeometryTrait`] implementation while retaining the
+/// extension trait wrappers.
 macro_rules! forward_geometry_trait_ext_funcs {
     ($t:ty) => {
         type PointTypeExt<'__g_inner>

rust/sedona-geo-traits-ext/src/geometry_collection.rs

@@ -21,15 +21,23 @@ use geo_types::{CoordNum, GeometryCollection};
 
 use crate::{GeoTraitExtWithTypeTag, GeometryCollectionTag, GeometryTraitExt};
 
+/// Extension trait that enriches [`geo_traits::GeometryCollectionTrait`] with
+/// Sedona-specific conveniences.
+///
+/// The trait exposes accessor methods that return geometry values wrapped in
+/// [`GeometryTraitExt`], enabling downstream consumers to leverage the unified
+/// extension API regardless of the backing geometry type.
 pub trait GeometryCollectionTraitExt:
     GeometryCollectionTrait + GeoTraitExtWithTypeTag<Tag = GeometryCollectionTag>
 where
     <Self as GeometryTrait>::T: CoordNum,
 {
+    /// Extension-aware geometry type yielded by accessor methods.
     type GeometryTypeExt<'a>: 'a + GeometryTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Returns the geometry at index `i`, wrapped with [`GeometryTraitExt`].
     fn geometry_ext(&self, i: usize) -> Option<Self::GeometryTypeExt<'_>>;
 
     /// Returns a geometry by index without bounds checking.
@@ -39,10 +47,14 @@ where
     /// Otherwise, this function may cause undefined behavior.
     unsafe fn geometry_unchecked_ext(&self, i: usize) -> Self::GeometryTypeExt<'_>;
 
+    /// Iterates over all geometries in the collection with extension wrappers applied.
     fn geometries_ext(&self) -> impl Iterator<Item = Self::GeometryTypeExt<'_>>;
 }
 
 #[macro_export]
+/// Forwards [`GeometryCollectionTraitExt`] methods to the underlying
+/// [`geo_traits::GeometryCollectionTrait`] implementation while preserving the
+/// extension trait wrappers.
 macro_rules! forward_geometry_collection_trait_ext_funcs {
     () => {
         type GeometryTypeExt<'__gc_inner>

rust/sedona-geo-traits-ext/src/line.rs

@@ -21,6 +21,7 @@ use geo_types::{CoordNum, Line};
 
 use crate::{CoordTraitExt, GeoTraitExtWithTypeTag, LineTag};
 
+/// Extra helpers for [`LineTrait`] implementors that mirror `geo-types` APIs.
 pub trait LineTraitExt: LineTrait + GeoTraitExtWithTypeTag<Tag = LineTag>
 where
     <Self as GeometryTrait>::T: CoordNum,
@@ -29,27 +30,34 @@ where
     where
         Self: 'a;
 
+    /// Returns the start coordinate as an extension trait instance.
     fn start_ext(&self) -> Self::CoordTypeExt<'_>;
+    /// Returns the end coordinate as an extension trait instance.
     fn end_ext(&self) -> Self::CoordTypeExt<'_>;
+    /// Returns both start and end coordinates in a fixed-size array.
     fn coords_ext(&self) -> [Self::CoordTypeExt<'_>; 2];
 
     #[inline]
+    /// Returns the start coordinate converted to [`geo_types::Coord`].
     fn start_coord(&self) -> geo_types::Coord<<Self as GeometryTrait>::T> {
         self.start_ext().geo_coord()
     }
 
     #[inline]
+    /// Returns the end coordinate converted to [`geo_types::Coord`].
     fn end_coord(&self) -> geo_types::Coord<<Self as GeometryTrait>::T> {
         self.end_ext().geo_coord()
     }
 
     #[inline]
+    /// Returns the line converted to a [`geo_types::Line`].
     fn geo_line(&self) -> Line<<Self as GeometryTrait>::T> {
         Line::new(self.start_coord(), self.end_coord())
     }
 }
 
 #[macro_export]
+/// Forwards [`LineTraitExt`] methods to an underlying [`LineTrait`] implementation.
 macro_rules! forward_line_trait_ext_funcs {
     () => {
         type CoordTypeExt<'__l_inner>

rust/sedona-geo-traits-ext/src/line_string.rs

@@ -21,6 +21,7 @@ use geo_types::{Coord, CoordNum, Line, LineString, Triangle};
 
 use crate::{CoordTraitExt, GeoTraitExtWithTypeTag, LineStringTag};
 
+/// Additional convenience methods for [`LineStringTrait`] implementors that mirror `geo-types`.
 pub trait LineStringTraitExt:
     LineStringTrait + GeoTraitExtWithTypeTag<Tag = LineStringTag>
 where
@@ -30,6 +31,7 @@ where
     where
         Self: 'a;
 
+    /// Returns the coordinate at the provided index.
     fn coord_ext(&self, i: usize) -> Option<Self::CoordTypeExt<'_>>;
 
     /// Returns a coordinate by index without bounds checking.
@@ -39,6 +41,7 @@ where
     /// Otherwise, this function may cause undefined behavior.
     unsafe fn coord_unchecked_ext(&self, i: usize) -> Self::CoordTypeExt<'_>;
 
+    /// Returns an iterator over all coordinates as extension trait instances.
     fn coords_ext(&self) -> impl Iterator<Item = Self::CoordTypeExt<'_>>;
 
     /// Returns a coordinate by index without bounds checking.
@@ -92,13 +95,14 @@ where
         })
     }
 
-    // Returns an iterator yielding the coordinates of this line string as `geo_types::Coord`s.
+    /// Returns an iterator yielding the coordinates of this line string as [`geo_types::Coord`] values.
     #[inline]
     fn coord_iter(&self) -> impl Iterator<Item = Coord<<Self as GeometryTrait>::T>> {
         self.coords_ext().map(|c| c.geo_coord())
     }
 
     #[inline]
+    /// Returns true when the line string is closed (its first and last coordinates are equal).
     fn is_closed(&self) -> bool {
         match (self.coords_ext().next(), self.coords_ext().last()) {
             (Some(first), Some(last)) => first.geo_coord() == last.geo_coord(),
@@ -109,6 +113,7 @@ where
 }
 
 #[macro_export]
+/// Forwards [`LineStringTraitExt`] methods to an underlying [`LineStringTrait`] implementation.
 macro_rules! forward_line_string_trait_ext_funcs {
     () => {
         type CoordTypeExt<'__l_inner>

rust/sedona-geo-traits-ext/src/multi_line_string.rs

@@ -21,15 +21,26 @@ use geo_types::{CoordNum, MultiLineString};
 
 use crate::{GeoTraitExtWithTypeTag, LineStringTraitExt, MultiLineStringTag};
 
+/// Extension trait that layers additional ergonomics on
+/// [`geo_traits::MultiLineStringTrait`].
+///
+/// Implementors gain access to extension-aware iterators and helper methods
+/// that mirror the behavior of `geo-types::MultiLineString`, while still being
+/// consumable through the trait abstractions provided by `geo-traits`.
 pub trait MultiLineStringTraitExt:
     MultiLineStringTrait + GeoTraitExtWithTypeTag<Tag = MultiLineStringTag>
 where
     <Self as GeometryTrait>::T: CoordNum,
 {
+    /// Extension-friendly line string type returned by accessor methods.
     type LineStringTypeExt<'a>: 'a + LineStringTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Returns the line string at index `i` with the extension trait applied.
+    ///
+    /// This is analogous to [`geo_traits::MultiLineStringTrait::line_string`]
+    /// but ensures the result implements [`LineStringTraitExt`].
     fn line_string_ext(&self, i: usize) -> Option<Self::LineStringTypeExt<'_>>;
 
     /// Returns a line string by index without bounds checking.
@@ -39,9 +50,10 @@ where
     /// Otherwise, this function may cause undefined behavior.
     unsafe fn line_string_unchecked_ext(&self, i: usize) -> Self::LineStringTypeExt<'_>;
 
+    /// Iterates over all line strings with extension-aware wrappers applied.
     fn line_strings_ext(&self) -> impl Iterator<Item = Self::LineStringTypeExt<'_>>;
 
-    /// True if the MultiLineString is empty or if all of its LineStrings are closed
+    /// Returns `true` when the multi line string is empty or every component is closed.
     #[inline]
     fn is_closed(&self) -> bool {
         // Note: Unlike JTS et al, we consider an empty MultiLineString as closed.
@@ -50,6 +62,9 @@ where
 }
 
 #[macro_export]
+/// Forwards [`MultiLineStringTraitExt`] methods to the underlying
+/// [`geo_traits::MultiLineStringTrait`] implementation while keeping the
+/// extension trait wrappers intact.
 macro_rules! forward_multi_line_string_trait_ext_funcs {
     () => {
         type LineStringTypeExt<'__l_inner>

rust/sedona-geo-traits-ext/src/multi_point.rs

@@ -21,15 +21,28 @@ use geo_types::{Coord, CoordNum, MultiPoint};
 
 use crate::{CoordTraitExt, GeoTraitExtWithTypeTag, MultiPointTag, PointTraitExt};
 
+/// Extension trait that augments [`geo_traits::MultiPointTrait`] with richer
+/// ergonomics and accessors.
+///
+/// The trait keeps parity with the APIs provided by `geo-types::MultiPoint`
+/// while still working with trait objects that only implement
+/// [`geo_traits::MultiPointTrait`]. It also wires the geometry up with a
+/// [`MultiPointTag`](crate::MultiPointTag) so the type can participate in the
+/// shared `GeoTraitExtWithTypeTag` machinery.
 pub trait MultiPointTraitExt:
     MultiPointTrait + GeoTraitExtWithTypeTag<Tag = MultiPointTag>
 where
     <Self as GeometryTrait>::T: CoordNum,
 {
+    /// Extension-aware point type returned from accessors on this multi point.
     type PointTypeExt<'a>: 'a + PointTraitExt<T = <Self as GeometryTrait>::T>
     where
         Self: 'a;
 
+    /// Returns the point at index `i`, wrapped in the extension trait.
+    ///
+    /// This mirrors [`geo_traits::MultiPointTrait::point`] but guarantees the
+    /// returned point implements [`PointTraitExt`].
     fn point_ext(&self, i: usize) -> Option<Self::PointTypeExt<'_>>;
 
     /// Returns a point by index without bounds checking.
@@ -44,21 +57,39 @@ where
     /// # Safety
     /// The caller must ensure that `i` is a valid index less than the number of points.
     /// Otherwise, this function may cause undefined behavior.
+    /// Returns the coordinate at index `i` without bounds checking.
+    ///
+    /// This helper is primarily used by iterator adapters that need direct
+    /// coordinate access while still honoring the [`PointTraitExt`] abstraction.
+    ///
+    /// # Safety
+    /// The caller must ensure that `i` is a valid index less than the number of points.
+    /// Otherwise, this function may cause undefined behavior.
     #[inline]
     unsafe fn geo_coord_unchecked(&self, i: usize) -> Option<Coord<<Self as GeometryTrait>::T>> {
         let point = unsafe { self.point_unchecked_ext(i) };
         point.coord_ext().map(|c| c.geo_coord())
     }
 
+    /// Returns an iterator over all points, each wrapped in [`PointTraitExt`].
     fn points_ext(&self) -> impl DoubleEndedIterator<Item = Self::PointTypeExt<'_>>;
 
+    /// Iterates over the coordinates contained in this multi point.
+    ///
+    /// For trait-based implementations this is derived from
+    /// [`points_ext`](Self::points_ext), while concrete `geo-types::MultiPoint`
+    /// instances provide a specialized iterator that avoids intermediate
+    /// allocations.
     #[inline]
     fn coord_iter(&self) -> impl DoubleEndedIterator<Item = Coord<<Self as GeometryTrait>::T>> {
         self.points_ext().flat_map(|p| p.geo_coord())
     }
 }
 
 #[macro_export]
+/// Forwards [`MultiPointTraitExt`] methods to the underlying
+/// [`geo_traits::MultiPointTrait`] implementation while maintaining the
+/// extension trait wrappers.
 macro_rules! forward_multi_point_trait_ext_funcs {
     () => {
         type PointTypeExt<'__l_inner>
@@ -89,6 +120,7 @@ where
 {
     forward_multi_point_trait_ext_funcs!();
 
+    /// Specialized coordinate accessor for `geo_types::MultiPoint`.
     unsafe fn geo_coord_unchecked(&self, i: usize) -> Option<Coord<T>> {
         Some(self.0.get_unchecked(i).0)
     }
@@ -109,6 +141,7 @@ where
 {
     forward_multi_point_trait_ext_funcs!();
 
+    /// Specialized coordinate accessor for `&geo_types::MultiPoint`.
     unsafe fn geo_coord_unchecked(&self, i: usize) -> Option<Coord<T>> {
         Some(self.0.get_unchecked(i).0)
     }