Improve documentation clarity across schema and constraint classes

packages/ack/lib/src/ack.dart

@@ -49,6 +49,7 @@ final class Ack {
   static EnumSchema<T> enumValues<T extends Enum>(List<T> values) =>
       EnumSchema(values: values);
 
+  /// Creates a string schema that only accepts one of the given [values].
   static StringSchema enumString(List<String> values) =>
       string().withConstraint(PatternConstraint.enumString(values));
 

packages/ack/lib/src/constraints/comparison_constraint.dart

@@ -25,10 +25,7 @@ _ConstraintCategory _categorize(String constraintKey) {
 ///
 /// This versatile constraint handles comparisons like minimum/maximum length for strings/lists,
 /// min/max value for numbers, property counts for objects, etc., by using a
-/// `valueExtractor` function to get a numeric value from the input type `T`.
-///
-/// It is generic on the non-nullable type `T`, but validates the nullable type `T?`.
-/// It will always pass if the input value is `null`.
+/// [valueExtractor] function to get a numeric value from the input type [T].
 class ComparisonConstraint<T extends Object> extends Constraint<T>
     with Validator<T>, JsonSchemaSpec<T> {
   final ComparisonType type;

packages/ack/lib/src/constraints/string_literal_constraint.dart

@@ -1,9 +1,8 @@
 import 'constraint.dart';
 
-/// Validates that an input string is exactly equal to an `expectedValue`.
+/// Validates that an input string is exactly equal to an [expectedValue].
 ///
 /// Useful for discriminator fields or fixed value properties.
-/// It will always pass if the input value is `null`.
 class StringLiteralConstraint extends Constraint<String>
     with Validator<String>, JsonSchemaSpec<String> {
   final String expectedValue;

packages/ack/lib/src/constraints/validators.dart

@@ -19,7 +19,8 @@ class NonNullableConstraint extends Constraint<Object?>
 }
 
 /// Constraint for validating that a value is of an expected Dart type.
-/// Typically used internally by `AckSchema.tryConvertInput`.
+///
+/// Used internally by [AckSchema] during type checking in `parseAndValidate`.
 class InvalidTypeConstraint extends Constraint<Object?>
     with Validator<Object?> {
   final Type expectedType;

packages/ack/lib/src/schemas/extensions/ack_schema_extensions.dart

@@ -60,7 +60,8 @@ extension AckSchemaExtensions<T extends Object> on AckSchema<T> {
 
   /// Transforms the validated value using the provided transformer function.
   ///
-  /// The transformer is applied after all validations pass.
+  /// The transformer receives `T?` because the base schema may be nullable or
+  /// optional, meaning `null` is a valid validated value.
   /// This is useful for converting data types or applying business logic transformations.
   TransformedSchema<T, R> transform<R extends Object>(
     R Function(T? value) transformer,

packages/ack/lib/src/schemas/extensions/list_schema_extensions.dart

@@ -9,23 +9,23 @@ extension ListSchemaExtensions<T extends Object> on ListSchema<T> {
     return withConstraint(ComparisonConstraint.listMinItems<T>(n));
   }
 
-  /// Alias for [minItems] to mirror documentation naming.
+  /// Alias for [minItems].
   ListSchema<T> minLength(int n) => minItems(n);
 
   /// Adds a constraint that the list must have no more than [n] items.
   ListSchema<T> maxItems(int n) {
     return withConstraint(ComparisonConstraint.listMaxItems<T>(n));
   }
 
-  /// Alias for [maxItems] to mirror documentation naming.
+  /// Alias for [maxItems].
   ListSchema<T> maxLength(int n) => maxItems(n);
 
   /// Adds a constraint that the list must have exactly [n] items.
   ListSchema<T> exactLength(int n) {
     return withConstraint(ComparisonConstraint.listExactItems<T>(n));
   }
 
-  /// Alias for [exactLength] to mirror documentation naming.
+  /// Alias for [exactLength].
   ListSchema<T> length(int n) => exactLength(n);
 
   /// Adds a constraint that the list must not be empty.
@@ -34,7 +34,7 @@ extension ListSchemaExtensions<T extends Object> on ListSchema<T> {
     return minItems(1);
   }
 
-  /// Alias for [nonEmpty] to mirror documentation naming.
+  /// Alias for [nonEmpty].
   ListSchema<T> notEmpty() => nonEmpty();
 
   /// Adds a constraint that all items in the list must be unique.

packages/ack/lib/src/schemas/extensions/object_schema_extensions.dart

@@ -43,11 +43,8 @@ extension ObjectSchemaExtensions on ObjectSchema {
 
   /// Extends this schema with additional or overridden properties.
   ///
-  /// Acts like an additional constructor, allowing you to override properties
-  /// one by one and add additional properties and construction elements.
-  ///
   /// Properties in [newProperties] will override existing properties with the same key.
-  /// Other schema properties can be overridden using the optional parameters.
+  /// Other schema settings can be overridden using the optional parameters.
   ObjectSchema extend(
     Map<String, AckSchema> newProperties, {
     bool? additionalProperties,

packages/ack/lib/src/schemas/extensions/string_schema_extensions.dart

@@ -32,7 +32,9 @@ extension StringSchemaExtensions on StringSchema {
     return withConstraint(PatternConstraint.email());
   }
 
-  /// Adds a constraint that the string must be a valid URL.
+  /// Adds a constraint that the string must be a valid URI.
+  ///
+  /// This is an alias for [uri]. Validates absolute URIs with a scheme and host.
   StringSchema url() {
     return withConstraint(PatternConstraint.uri());
   }

packages/ack/lib/src/schemas/fluent_schema.dart

@@ -9,7 +9,9 @@ mixin FluentSchema<DartType extends Object, Schema extends AckSchema<DartType>>
   /// Marks the schema as nullable.
   Schema nullable({bool value = true}) => copyWith(isNullable: value) as Schema;
 
-  /// Marks the schema as optional (field can be omitted from an object).
+  /// Marks the schema as optional so the field can be omitted from an object.
+  ///
+  /// See [AckSchemaExtensions.optional] for detailed semantics.
   Schema optional({bool value = true}) => copyWith(isOptional: value) as Schema;
 
   /// Sets the description for the schema.