doc: update extensions types and links

Author: wackywendell

src/parse/text/mod.rs

@@ -1,5 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
-//! Parsing of [text](crate::text) types.
+//! Utilities for working with Substrait *text* objects.
+//!
+//! The generated [`crate::text`] module exposes the raw YAML-derived structs
+//! (e.g. [`crate::text::simple_extensions::SimpleExtensions`]).  This module
+//! provides parsing helpers that validate those raw values and offer
+//! higher-level wrappers for validation, lookups, and combining into protobuf
+//! objects.
 
 pub mod simple_extensions;

src/parse/text/simple_extensions/argument.rs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
-//! Parsing of [simple_extensions::ArgumentsItem].
+//! Parsing of type arguments: [`simple_extensions::ArgumentsItem`].
 
 use std::{collections::HashSet, ops::Deref};
 
@@ -11,21 +11,24 @@ use crate::{
     text::simple_extensions,
 };
 
-/// A parsed [simple_extensions::ArgumentsItem].
+/// A parsed [`simple_extensions::ArgumentsItem`].
 #[derive(Clone, Debug)]
 pub enum ArgumentsItem {
-    /// Arguments that support a fixed set of declared values as constant arguments.
+    /// Arguments that support a fixed set of declared values as constant
+    /// arguments.
     EnumArgument(EnumerationArg),
 
     /// Arguments that refer to a data value.
     ValueArgument(ValueArg),
 
-    /// Arguments that are used only to inform the evaluation and/or type derivation of the function.
+    /// Arguments that are used only to inform the evaluation and/or type
+    /// derivation of the function.
     TypeArgument(TypeArg),
 }
 
 impl ArgumentsItem {
-    /// Parses an `Option<String>` field, rejecting it if an empty string is provided.
+    /// Parses an `Option<String>` field, rejecting it if an empty string is
+    /// provided.
     #[inline]
     fn parse_optional_string(
         name: &str,
@@ -75,7 +78,7 @@ impl From<ArgumentsItem> for simple_extensions::ArgumentsItem {
     }
 }
 
-/// Parse errors for [simple_extensions::ArgumentsItem].
+/// Parse errors for [`simple_extensions::ArgumentsItem`].
 #[derive(Debug, Error, PartialEq)]
 pub enum ArgumentsItemError {
     /// Invalid enumeration options.
@@ -103,21 +106,21 @@ pub struct EnumerationArg {
 impl EnumerationArg {
     /// Returns the name of this argument.
     ///
-    /// See [simple_extensions::EnumerationArg::name].
+    /// See [`simple_extensions::EnumerationArg::name`].
     pub fn name(&self) -> Option<&String> {
         self.name.as_ref()
     }
 
     /// Returns the description of this argument.
     ///
-    /// See [simple_extensions::EnumerationArg::description].
+    /// See [`simple_extensions::EnumerationArg::description`].
     pub fn description(&self) -> Option<&String> {
         self.description.as_ref()
     }
 
     /// Returns the options of this argument.
     ///
-    /// See [simple_extensions::EnumerationArg::options].
+    /// See [`simple_extensions::EnumerationArg::options`].
     pub fn options(&self) -> &EnumOptions {
         &self.options
     }
@@ -210,7 +213,7 @@ impl From<EnumOptions> for simple_extensions::EnumOptions {
     }
 }
 
-/// Parse errors for [simple_extensions::EnumOptions].
+/// Parse errors for [`simple_extensions::EnumOptions`].
 #[derive(Debug, Error, PartialEq)]
 pub enum EnumOptionsError {
     /// Empty list.
@@ -237,35 +240,35 @@ pub struct ValueArg {
 
     /// A fully defined type or a type expression.
     ///
-    /// TODO: parse this to a typed representation (likely using the `TypeExpr` parser)
-    /// so the caller does not have to interpret the raw string.
+    /// TODO: parse this to a typed representation (likely using the `TypeExpr`
+    /// parser) so the caller does not have to interpret the raw string.
     value: simple_extensions::Type,
 
-    /// Whether this argument is required to be a constant for invocation.
-    /// For example, in some system a regular expression pattern would only be accepted as a literal
-    /// and not a column value reference.
+    /// Whether this argument is required to be a constant for invocation. For
+    /// example, in some system a regular expression pattern would only be
+    /// accepted as a literal and not a column value reference.
     constant: Option<bool>,
 }
 
 impl ValueArg {
     /// Returns the name of this argument.
     ///
-    /// See [simple_extensions::ValueArg::name].
+    /// See [`simple_extensions::ValueArg::name`].
     pub fn name(&self) -> Option<&String> {
         self.name.as_ref()
     }
 
     /// Returns the description of this argument.
     ///
-    /// See [simple_extensions::ValueArg::description].
+    /// See [`simple_extensions::ValueArg::description`].
     pub fn description(&self) -> Option<&String> {
         self.description.as_ref()
     }
 
     /// Returns the constant of this argument.
     /// Defaults to `false` if the underlying value is `None`.
     ///
-    /// See [simple_extensions::ValueArg::constant].
+    /// See [`simple_extensions::ValueArg::constant`].
     pub fn constant(&self) -> bool {
         self.constant.unwrap_or(false)
     }
@@ -309,33 +312,33 @@ impl From<ValueArg> for ArgumentsItem {
     }
 }
 
-/// Arguments that are used only to inform the evaluation and/or type derivation of the function.
+/// A type argument to a parameterized type, e.g. the `T` in `List<T>`.
 #[derive(Clone, Debug, PartialEq)]
 pub struct TypeArg {
-    /// A human-readable name for this argument to help clarify use.
+    /// A human-readable name for this argument to clarify use.
     name: Option<String>,
 
     /// Additional description for this argument.
     description: Option<String>,
 
     /// A partially or completely parameterized type. E.g. `List<K>` or `K`.
     ///
-    /// TODO: parse this to a typed representation (likely using the `TypeExpr` parser)
-    /// so the caller does not have to interpret the raw string.
+    /// TODO: parse this to a typed representation (likely using the `TypeExpr`
+    /// parser) so the caller does not have to interpret the raw string.
     type_: String,
 }
 
 impl TypeArg {
     /// Returns the name of this argument.
     ///
-    /// See [simple_extensions::TypeArg::name].
+    /// See [`simple_extensions::TypeArg::name`].
     pub fn name(&self) -> Option<&String> {
         self.name.as_ref()
     }
 
     /// Returns the description of this argument.
     ///
-    /// See [simple_extensions::TypeArg::description].
+    /// See [`simple_extensions::TypeArg::description`].
     pub fn description(&self) -> Option<&String> {
         self.description.as_ref()
     }

src/parse/text/simple_extensions/extensions.rs

@@ -12,20 +12,22 @@ use crate::{
     urn::Urn,
 };
 
-/// Parsing context for extension processing
+/// The contents (types) in an [`ExtensionFile`](super::file::ExtensionFile).
 ///
-/// The context provides access to types defined in the same extension file during parsing.
-/// This allows type references to be resolved within the same extension file. The corresponding
-/// URN is tracked by [`ExtensionFile`](super::file::ExtensionFile) so this structure can focus on
-/// validated type information.
+/// This structure stores and provides access to the individual objects defined
+/// in an [`ExtensionFile`](super::file::ExtensionFile); [`SimpleExtensions`]
+/// represents the contents of an extensions file.
+///
+/// Currently, only the [`CustomType`]s are included; any scalar, window, or
+/// aggregate functions are not yet included.
 #[derive(Clone, Debug, Default)]
 pub struct SimpleExtensions {
     /// Types defined in this extension file
     types: HashMap<String, CustomType>,
 }
 
 impl SimpleExtensions {
-    /// Add a type to the context
+    /// Add a type to the context. Name must be unique.
     pub fn add_type(&mut self, custom_type: &CustomType) -> Result<(), SimpleExtensionsError> {
         if self.types.contains_key(&custom_type.name) {
             return Err(SimpleExtensionsError::DuplicateTypeName {
@@ -59,7 +61,8 @@ impl SimpleExtensions {
     }
 }
 
-/// A context for parsing simple extensions.
+/// A context for parsing simple extensions, tracking what type names are
+/// resolved or unresolved.
 #[derive(Debug, Default)]
 pub struct TypeContext {
     /// Types that have been seen so far, now resolved.
@@ -75,7 +78,8 @@ impl TypeContext {
         self.known.insert(name.to_string());
     }
 
-    /// Mark a type as linked to - some other type or function references it, but we haven't seen it.
+    /// Mark a type as linked to - some other type or function references it,
+    /// but we haven't seen it.
     pub fn linked(&mut self, name: &str) {
         if !self.known.contains(name) {
             self.linked.insert(name.to_string());

src/parse/text/simple_extensions/file.rs

@@ -7,11 +7,10 @@ use crate::text::simple_extensions::SimpleExtensions as RawExtensions;
 use crate::urn::Urn;
 use std::io::Read;
 
-/// A parsed and validated [RawExtensions].
+/// A parsed and validated [`RawExtensions`]: a simple extensions file.
 ///
-/// `ExtensionFile` owns the canonical URN for a simple extension file along with the parsed
-/// [`SimpleExtensions`](super::SimpleExtensions) data. Keeping the URN here (instead of on the inner
-/// type map) lets us thread it through I/O, registries, and conversions without duplicating state.
+/// An [`ExtensionFile`] has a canonical [`Urn`] and a parsed set of
+/// [`SimpleExtensions`] data. It represents the extensions file as a whole.
 #[derive(Debug)]
 pub struct ExtensionFile {
     /// The URN this extension was loaded from
@@ -21,13 +20,13 @@ pub struct ExtensionFile {
 }
 
 impl ExtensionFile {
-    /// Create a new, empty SimpleExtensions
+    /// Create a new, empty [`ExtensionFile`] with an empty set of [`SimpleExtensions`].
     pub fn empty(urn: Urn) -> Self {
         let extension = SimpleExtensions::default();
         Self { urn, extension }
     }
 
-    /// Create a validated SimpleExtensions from raw data
+    /// Create an [`ExtensionFile`] from raw simple extension data.
     pub fn create(extensions: RawExtensions) -> Result<Self, SimpleExtensionsError> {
         // Parse all types (may contain unresolved Extension(String) references)
         let mut ctx = TypeContext::default();
@@ -48,31 +47,33 @@ impl ExtensionFile {
         self.extension.types()
     }
 
-    /// Returns the URN for this extension file.
+    /// Returns the [`Urn`]` for this extension file.
     pub fn urn(&self) -> &Urn {
         &self.urn
     }
 
-    /// Get a reference to the underlying SimpleExtension
+    /// Get a reference to the underlying [`SimpleExtensions`].
     pub fn extension(&self) -> &SimpleExtensions {
         &self.extension
     }
 
-    /// Convert the parsed extension file back into the raw text representation by value.
+    /// Convert the parsed extension file back into the raw text representation
+    /// by value.
     pub fn into_raw(self) -> RawExtensions {
         let ExtensionFile { urn, extension } = self;
         RawExtensions::from((urn, extension))
     }
 
-    /// Convert the parsed extension file back into the raw text representation by reference.
+    /// Convert the parsed extension file back into the raw text representation
+    /// by reference.
     pub fn to_raw(&self) -> RawExtensions {
         RawExtensions::from((self.urn.clone(), self.extension.clone()))
     }
 
     /// Read an extension file from a reader.
-    /// - `reader`: any `Read` instance with the YAML content
+    /// - `reader`: any [`Read`] instance with the YAML content
     ///
-    /// Returns a parsed and validated `ExtensionFile` or an error.
+    /// Returns a parsed and validated [`ExtensionFile`] or an error.
     pub fn read<R: Read>(reader: R) -> Result<Self, SimpleExtensionsError> {
         let raw: RawExtensions = serde_yaml::from_reader(reader)?;
         Self::create(raw)

src/parse/text/simple_extensions/mod.rs

@@ -1,6 +1,18 @@
 // SPDX-License-Identifier: Apache-2.0
 
-//! Parsing of [crate::text::simple_extensions] types into [SimpleExtensions].
+//! Rustic types for validating and working with Substrait simple extensions.
+//!
+//! The raw YAML structs live in [`crate::text::simple_extensions`].  This
+//! module parses those values into the typed representations used by this
+//! crate:
+//! * [`ExtensionFile`] – a fully validated extension document (URN plus its
+//!   definitions).
+//! * [`SimpleExtensions`] – the validated objects declared by a single
+//!   extension file.
+//! * [`CustomType`] / [`ConcreteType`] – type definitions and resolved type
+//!   structures used when checking function signatures.
+//! * [`Registry`] – a reusable lookup structure that stores validated extension
+//!   files and exposes typed access to their contents.
 
 use std::convert::Infallible;
 

src/parse/text/simple_extensions/parsed_type.rs

@@ -34,7 +34,7 @@ pub enum TypeParseError {
 }
 
 impl<'a> TypeExpr<'a> {
-    /// Parse a type string into a ParsedType
+    /// Parse a type string into a [`TypeExpr`].
     pub fn parse(type_str: &'a str) -> Result<Self, TypeParseError> {
         // Handle type variables like any1, any2, etc.
         if let Some(suffix) = type_str.strip_prefix("any") {