From e111eb266d19dd97d7759e9f23f6b79dd9ebd0d8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Mar 2026 17:59:09 +0000 Subject: [PATCH 1/2] Fix documentation drift and apply Dart commenting guidelines - Remove misleading "always passes if null" claims from StringLiteralConstraint and ComparisonConstraint (isValid takes non-nullable types; null is handled upstream by AckSchema.handleNullInput) - Fix url() doc to say URI instead of URL, matching PatternConstraint.uri() - Remove vague "construction elements" from ObjectSchemaExtensions.extend() - Fix InvalidTypeConstraint reference to removed tryConvertInput method - Simplify ListSchemaExtensions alias comments (remove unclear "mirror documentation naming") - Add doc comment to FluentSchema.optional() with cross-reference - Add missing doc comment to Ack.enumString() https://claude.ai/code/session_016wyFrpbjHmLNXzKn4BQ5d7 --- packages/ack/lib/src/ack.dart | 1 + .../ack/lib/src/constraints/comparison_constraint.dart | 5 +---- .../lib/src/constraints/string_literal_constraint.dart | 3 +-- packages/ack/lib/src/constraints/validators.dart | 3 ++- .../src/schemas/extensions/list_schema_extensions.dart | 8 ++++---- .../src/schemas/extensions/object_schema_extensions.dart | 5 +---- .../src/schemas/extensions/string_schema_extensions.dart | 4 +++- packages/ack/lib/src/schemas/fluent_schema.dart | 4 +++- 8 files changed, 16 insertions(+), 17 deletions(-) diff --git a/packages/ack/lib/src/ack.dart b/packages/ack/lib/src/ack.dart index e4eda6f4..afc25d69 100644 --- a/packages/ack/lib/src/ack.dart +++ b/packages/ack/lib/src/ack.dart @@ -49,6 +49,7 @@ final class Ack { static EnumSchema enumValues(List values) => EnumSchema(values: values); + /// Creates a string schema that only accepts one of the given [values]. static StringSchema enumString(List values) => string().withConstraint(PatternConstraint.enumString(values)); diff --git a/packages/ack/lib/src/constraints/comparison_constraint.dart b/packages/ack/lib/src/constraints/comparison_constraint.dart index 7ce72d98..c8b8546b 100644 --- a/packages/ack/lib/src/constraints/comparison_constraint.dart +++ b/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 extends Constraint with Validator, JsonSchemaSpec { final ComparisonType type; diff --git a/packages/ack/lib/src/constraints/string_literal_constraint.dart b/packages/ack/lib/src/constraints/string_literal_constraint.dart index a36c2550..a390f3be 100644 --- a/packages/ack/lib/src/constraints/string_literal_constraint.dart +++ b/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 with Validator, JsonSchemaSpec { final String expectedValue; diff --git a/packages/ack/lib/src/constraints/validators.dart b/packages/ack/lib/src/constraints/validators.dart index badcf5bf..64453532 100644 --- a/packages/ack/lib/src/constraints/validators.dart +++ b/packages/ack/lib/src/constraints/validators.dart @@ -19,7 +19,8 @@ class NonNullableConstraint extends Constraint } /// 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 with Validator { final Type expectedType; diff --git a/packages/ack/lib/src/schemas/extensions/list_schema_extensions.dart b/packages/ack/lib/src/schemas/extensions/list_schema_extensions.dart index 5126c66a..62920e09 100644 --- a/packages/ack/lib/src/schemas/extensions/list_schema_extensions.dart +++ b/packages/ack/lib/src/schemas/extensions/list_schema_extensions.dart @@ -9,7 +9,7 @@ extension ListSchemaExtensions on ListSchema { return withConstraint(ComparisonConstraint.listMinItems(n)); } - /// Alias for [minItems] to mirror documentation naming. + /// Alias for [minItems]. ListSchema minLength(int n) => minItems(n); /// Adds a constraint that the list must have no more than [n] items. @@ -17,7 +17,7 @@ extension ListSchemaExtensions on ListSchema { return withConstraint(ComparisonConstraint.listMaxItems(n)); } - /// Alias for [maxItems] to mirror documentation naming. + /// Alias for [maxItems]. ListSchema maxLength(int n) => maxItems(n); /// Adds a constraint that the list must have exactly [n] items. @@ -25,7 +25,7 @@ extension ListSchemaExtensions on ListSchema { return withConstraint(ComparisonConstraint.listExactItems(n)); } - /// Alias for [exactLength] to mirror documentation naming. + /// Alias for [exactLength]. ListSchema length(int n) => exactLength(n); /// Adds a constraint that the list must not be empty. @@ -34,7 +34,7 @@ extension ListSchemaExtensions on ListSchema { return minItems(1); } - /// Alias for [nonEmpty] to mirror documentation naming. + /// Alias for [nonEmpty]. ListSchema notEmpty() => nonEmpty(); /// Adds a constraint that all items in the list must be unique. diff --git a/packages/ack/lib/src/schemas/extensions/object_schema_extensions.dart b/packages/ack/lib/src/schemas/extensions/object_schema_extensions.dart index de66355d..ec1ca2e9 100644 --- a/packages/ack/lib/src/schemas/extensions/object_schema_extensions.dart +++ b/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 newProperties, { bool? additionalProperties, diff --git a/packages/ack/lib/src/schemas/extensions/string_schema_extensions.dart b/packages/ack/lib/src/schemas/extensions/string_schema_extensions.dart index 8ab8eb3a..ab2009f8 100644 --- a/packages/ack/lib/src/schemas/extensions/string_schema_extensions.dart +++ b/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()); } diff --git a/packages/ack/lib/src/schemas/fluent_schema.dart b/packages/ack/lib/src/schemas/fluent_schema.dart index 8de1b5f9..4d3df9cd 100644 --- a/packages/ack/lib/src/schemas/fluent_schema.dart +++ b/packages/ack/lib/src/schemas/fluent_schema.dart @@ -9,7 +9,9 @@ mixin FluentSchema> /// 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. From acccc7f9b1c15128cc1f5aa2f0591f5d213c1dd8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Mar 2026 18:45:41 +0000 Subject: [PATCH 2/2] Clarify transform() doc: transformer receives nullable T? The transformer function parameter is `T?` (nullable) because the base schema may be nullable or optional, making null a valid validated value. This is a critical API detail for callers. https://claude.ai/code/session_016wyFrpbjHmLNXzKn4BQ5d7 --- .../ack/lib/src/schemas/extensions/ack_schema_extensions.dart | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/ack/lib/src/schemas/extensions/ack_schema_extensions.dart b/packages/ack/lib/src/schemas/extensions/ack_schema_extensions.dart index 62202be1..41c26875 100644 --- a/packages/ack/lib/src/schemas/extensions/ack_schema_extensions.dart +++ b/packages/ack/lib/src/schemas/extensions/ack_schema_extensions.dart @@ -60,7 +60,8 @@ extension AckSchemaExtensions on AckSchema { /// 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 transform( R Function(T? value) transformer,