diff --git a/packages/ack/lib/src/ack.dart b/packages/ack/lib/src/ack.dart index e4eda6f..afc25d6 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 7ce72d9..c8b8546 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 a36c255..a390f3b 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 badcf5b..6445353 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/ack_schema_extensions.dart b/packages/ack/lib/src/schemas/extensions/ack_schema_extensions.dart index 62202be..41c2687 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, 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 5126c66..62920e0 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 de66355..ec1ca2e 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 8ab8eb3..ab2009f 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 8de1b5f..4d3df9c 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.