diff --git a/src/components/validator/src/constraints/blank.cr b/src/components/validator/src/constraints/blank.cr index cfb358f7..f5123312 100644 --- a/src/components/validator/src/constraints/blank.cr +++ b/src/components/validator/src/constraints/blank.cr @@ -1,5 +1,16 @@ # Validates that a value is blank; meaning equal to an empty string or `nil`. # +# ``` +# class Profile +# include AVD::Validatable +# +# def initialize(@username : String); end +# +# @[Assert::NotBlank] +# property username : String +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/choice.cr b/src/components/validator/src/constraints/choice.cr index 06772adf..a8e79c9d 100644 --- a/src/components/validator/src/constraints/choice.cr +++ b/src/components/validator/src/constraints/choice.cr @@ -1,6 +1,17 @@ # Validates that a value is one of a given set of valid choices; # can also be used to validate that each item in a collection is one of those valid values. # +# ``` +# class User +# include AVD::Validatable +# +# def initialize(@role : String); end +# +# @[Assert::Choice(["member", "moderator", "admin"])] +# property role : String +# end +# ``` +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/email.cr b/src/components/validator/src/constraints/email.cr index be872df4..aa320278 100644 --- a/src/components/validator/src/constraints/email.cr +++ b/src/components/validator/src/constraints/email.cr @@ -4,6 +4,17 @@ # NOTE: As with most other constraints, `nil` and empty strings are considered valid values, in order to allow the value to be optional. # If the value is required, consider combining this constraint with `AVD::Constraints::NotBlank`. # +# ``` +# class User +# include AVD::Validatable +# +# def initialize(@email : String); end +# +# @[Assert::Email] +# property email : String +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/equal_to.cr b/src/components/validator/src/constraints/equal_to.cr index c4c45fbb..38e74f89 100644 --- a/src/components/validator/src/constraints/equal_to.cr +++ b/src/components/validator/src/constraints/equal_to.cr @@ -1,5 +1,16 @@ # Validates that a value is equal to another. # +# ``` +# class Project +# include AVD::Validatable +# +# def initialize(@name : String); end +# +# @[Assert::EqualTo("Athena")] +# property name : String +# end +# ``` +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/file.cr b/src/components/validator/src/constraints/file.cr index 947210be..a72ae075 100644 --- a/src/components/validator/src/constraints/file.cr +++ b/src/components/validator/src/constraints/file.cr @@ -7,6 +7,17 @@ require "mime" # NOTE: As with most other constraints, `nil` and empty strings are considered valid values, in order to allow the value to be optional. # If the value is required, consider combining this constraint with `AVD::Constraints::NotBlank`. # +# ``` +# class Profile +# include AVD::Validatable +# +# def initialize(@resume : ::File); end +# +# @[Assert::File] +# property resume : ::File +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/greater_than.cr b/src/components/validator/src/constraints/greater_than.cr index e9e9849e..740516e7 100644 --- a/src/components/validator/src/constraints/greater_than.cr +++ b/src/components/validator/src/constraints/greater_than.cr @@ -1,5 +1,16 @@ # Validates that a value is greater than another. # +# ``` +# class Person +# include AVD::Validatable +# +# def initialize(@age : Int64); end +# +# @[Assert::GreaterThan(18)] +# property age : Int64 +# end +# ``` +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/greater_than_or_equal.cr b/src/components/validator/src/constraints/greater_than_or_equal.cr index 4413e979..4c0aeda8 100644 --- a/src/components/validator/src/constraints/greater_than_or_equal.cr +++ b/src/components/validator/src/constraints/greater_than_or_equal.cr @@ -1,5 +1,16 @@ # Validates that a value is greater than or equal to another. # +# ``` +# class Person +# include AVD::Validatable +# +# def initialize(@age : Int64); end +# +# @[Assert::GreaterThanOrEqual(18)] +# property age : Int64 +# end +# ``` +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/image.cr b/src/components/validator/src/constraints/image.cr index d85ea698..b8abe19a 100644 --- a/src/components/validator/src/constraints/image.cr +++ b/src/components/validator/src/constraints/image.cr @@ -5,6 +5,17 @@ require "athena-image_size" # # See `AVD::Constraints::File` for common documentation. # +# ``` +# class Profile +# include AVD::Validatable +# +# def initialize(@avatar : ::File); end +# +# @[Assert::Image] +# property avatar : ::File +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/ip.cr b/src/components/validator/src/constraints/ip.cr index 4222133e..3da7d4ef 100644 --- a/src/components/validator/src/constraints/ip.cr +++ b/src/components/validator/src/constraints/ip.cr @@ -7,6 +7,17 @@ require "socket" # NOTE: As with most other constraints, `nil` and empty strings are considered valid values, in order to allow the value to be optional. # If the value is required, consider combining this constraint with `AVD::Constraints::NotBlank`. # +# ``` +# class Machine +# include AVD::Validatable +# +# def initialize(@ip_address : String); end +# +# @[Assert::IP] +# property ip_address : String +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/is_false.cr b/src/components/validator/src/constraints/is_false.cr index c4ead99e..b7107572 100644 --- a/src/components/validator/src/constraints/is_false.cr +++ b/src/components/validator/src/constraints/is_false.cr @@ -1,5 +1,16 @@ # Validates that a value is `false`. # +# ``` +# class Post +# include AVD::Validatable +# +# def initialize(@is_published : Bool); end +# +# @[Assert::IsFalse] +# property is_published : Bool +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/is_nil.cr b/src/components/validator/src/constraints/is_nil.cr index cc199bb9..6b9bcfac 100644 --- a/src/components/validator/src/constraints/is_nil.cr +++ b/src/components/validator/src/constraints/is_nil.cr @@ -1,5 +1,16 @@ # Validates that a value is `nil`. # +# ``` +# class Post +# include AVD::Validatable +# +# def initialize(@updated_at : Time?); end +# +# @[Assert::IsNil] +# property updated_at : Time? +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/is_true.cr b/src/components/validator/src/constraints/is_true.cr index 1761e675..73af6523 100644 --- a/src/components/validator/src/constraints/is_true.cr +++ b/src/components/validator/src/constraints/is_true.cr @@ -1,5 +1,16 @@ # Validates that a value is `true`. # +# ``` +# class Post +# include AVD::Validatable +# +# def initialize(@is_published : Bool); end +# +# @[Assert::IsTrue] +# property is_published : Bool +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/isbn.cr b/src/components/validator/src/constraints/isbn.cr index 30551aac..2c7e50a0 100644 --- a/src/components/validator/src/constraints/isbn.cr +++ b/src/components/validator/src/constraints/isbn.cr @@ -4,6 +4,17 @@ # NOTE: As with most other constraints, `nil` and empty strings are considered valid values, in order to allow the value to be optional. # If the value is required, consider combining this constraint with `AVD::Constraints::NotBlank`. # +# ``` +# class Book +# include AVD::Validatable +# +# def initialize(@isbn : String); end +# +# @[Assert::ISBN] +# property isbn : String +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/isin.cr b/src/components/validator/src/constraints/isin.cr index 0b17c668..5ce0fff6 100644 --- a/src/components/validator/src/constraints/isin.cr +++ b/src/components/validator/src/constraints/isin.cr @@ -4,6 +4,16 @@ # NOTE: As with most other constraints, `nil` and empty strings are considered valid values, in order to allow the value to be optional. # If the value is required, consider combining this constraint with `AVD::Constraints::NotBlank`. # +# ``` +# class UnitAccount +# include AVD::Validatable +# +# def initialize(@isin : String); end +# +# @[Assert::ISIN] +# property isin : String +# end +# ``` # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/issn.cr b/src/components/validator/src/constraints/issn.cr index 77757af7..5b280390 100644 --- a/src/components/validator/src/constraints/issn.cr +++ b/src/components/validator/src/constraints/issn.cr @@ -4,6 +4,17 @@ # NOTE: As with most other constraints, `nil` and empty strings are considered valid values, in order to allow the value to be optional. # If the value is required, consider combining this constraint with `AVD::Constraints::NotBlank`. # +# ``` +# class Journal +# include AVD::Validatable +# +# def initialize(@isin : String); end +# +# @[Assert::ISSN] +# property issn : String +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/less_than.cr b/src/components/validator/src/constraints/less_than.cr index 5d2ad44b..0f2568d2 100644 --- a/src/components/validator/src/constraints/less_than.cr +++ b/src/components/validator/src/constraints/less_than.cr @@ -1,5 +1,16 @@ # Validates that a value is less than another. # +# ``` +# class Employee +# include AVD::Validatable +# +# def initialize(@age : Number); end +# +# @[Assert::LessThan(60)] +# property age : Number +# end +# ``` +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/less_than_or_equal.cr b/src/components/validator/src/constraints/less_than_or_equal.cr index 696fda20..6226476c 100644 --- a/src/components/validator/src/constraints/less_than_or_equal.cr +++ b/src/components/validator/src/constraints/less_than_or_equal.cr @@ -1,5 +1,16 @@ # Validates that a value is less than or equal to another. # +# ``` +# class Employee +# include AVD::Validatable +# +# def initialize(@age : Number); end +# +# @[Assert::LessThanOrEqual(60)] +# property age : Number +# end +# ``` +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/luhn.cr b/src/components/validator/src/constraints/luhn.cr index fe36c8f2..c88fc5f5 100644 --- a/src/components/validator/src/constraints/luhn.cr +++ b/src/components/validator/src/constraints/luhn.cr @@ -4,6 +4,17 @@ # NOTE: As with most other constraints, `nil` and empty strings are considered valid values, in order to allow the value to be optional. # If the value is required, consider combining this constraint with `AVD::Constraints::NotBlank`. # +# ``` +# class Transaction +# include AVD::Validatable +# +# def initialize(@card_number : String); end +# +# @[Assert::Luhn] +# property card_number : String +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/negative.cr b/src/components/validator/src/constraints/negative.cr index f8fb64ed..620db38f 100644 --- a/src/components/validator/src/constraints/negative.cr +++ b/src/components/validator/src/constraints/negative.cr @@ -1,6 +1,17 @@ # Validates that a value is a negative number. # Use `AVD::Constraints::NegativeOrZero` if you wish to also allow `0`. # +# ``` +# class Mall +# include AVD::Validatable +# +# def initialize(@lowest_floor : Number); end +# +# @[Assert::Negative] +# property lowest_floor : Number +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/negative_or_zero.cr b/src/components/validator/src/constraints/negative_or_zero.cr index fa410cc7..2f3f574b 100644 --- a/src/components/validator/src/constraints/negative_or_zero.cr +++ b/src/components/validator/src/constraints/negative_or_zero.cr @@ -1,6 +1,17 @@ # Validates that a value is a negative number, or `0`. # Use `AVD::Constraints::Negative` if you don't want to allow `0`. # +# ``` +# class Mall +# include AVD::Validatable +# +# def initialize(@lowest_floor : Number); end +# +# @[Assert::NegativeOrZero] +# property lowest_floor : Number +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/not_blank.cr b/src/components/validator/src/constraints/not_blank.cr index 9bf4ec7d..63e33ffd 100644 --- a/src/components/validator/src/constraints/not_blank.cr +++ b/src/components/validator/src/constraints/not_blank.cr @@ -1,5 +1,16 @@ # Validates that a value is not blank; meaning not equal to a blank string, an empty `Iterable`, `false`, or optionally `nil`. # +# ``` +# class User +# include AVD::Validatable +# +# def initialize(@name : String); end +# +# @[Assert::NotBlank] +# property name : String +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/not_equal_to.cr b/src/components/validator/src/constraints/not_equal_to.cr index bd4dcca6..926ef1f2 100644 --- a/src/components/validator/src/constraints/not_equal_to.cr +++ b/src/components/validator/src/constraints/not_equal_to.cr @@ -1,5 +1,16 @@ # Validates that a value is not equal to another. # +# ``` +# class User +# include AVD::Validatable +# +# def initialize(@name : String); end +# +# @[Assert::NotEqualTo("John Doe")] +# property name : String +# end +# ``` +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/not_nil.cr b/src/components/validator/src/constraints/not_nil.cr index f4ec8ab3..3faa7371 100644 --- a/src/components/validator/src/constraints/not_nil.cr +++ b/src/components/validator/src/constraints/not_nil.cr @@ -3,6 +3,20 @@ # NOTE: Due to Crystal's static typing, when validating objects the property's type must be nilable, # otherwise `nil` is inherently not allowed due to the compiler's type checking. # +# ``` +# class Post +# include AVD::Validatable +# +# def initialize(@title : String?, @description : String?); end +# +# @[Assert::NotNil] +# property title : String? +# +# @[Assert::NotNil] +# property description : String? +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/positive.cr b/src/components/validator/src/constraints/positive.cr index 563b4d19..d439de44 100644 --- a/src/components/validator/src/constraints/positive.cr +++ b/src/components/validator/src/constraints/positive.cr @@ -1,6 +1,17 @@ # Validates that a value is a positive number. # Use `AVD::Constraints::PositiveOrZero` if you wish to also allow `0`. # +# ``` +# class Account +# include AVD::Validatable +# +# def initialize(@balance : Number); end +# +# @[Assert::Positive] +# property balance : Number +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/positive_or_zero.cr b/src/components/validator/src/constraints/positive_or_zero.cr index d1cf2d62..8a802322 100644 --- a/src/components/validator/src/constraints/positive_or_zero.cr +++ b/src/components/validator/src/constraints/positive_or_zero.cr @@ -1,6 +1,17 @@ # Validates that a value is a positive number, or `0`. # Use `AVD::Constraints::Positive` if you don't want to allow `0`. # +# ``` +# class Account +# include AVD::Validatable +# +# def initialize(@balance : Number); end +# +# @[Assert::PositiveOrZero] +# property balance : Number +# end +# ``` +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/range.cr b/src/components/validator/src/constraints/range.cr index 0128e846..39c65596 100644 --- a/src/components/validator/src/constraints/range.cr +++ b/src/components/validator/src/constraints/range.cr @@ -1,5 +1,16 @@ # Validates that a `Number` or `Time` value is between some minimum and maximum. # +# ``` +# class House +# include AVD::Validatable +# +# def initialize(@area : Number); end +# +# @[Assert::Range(15..100)] +# property area : Number +# end +# ``` +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/regex.cr b/src/components/validator/src/constraints/regex.cr index 3adce69a..26410a19 100644 --- a/src/components/validator/src/constraints/regex.cr +++ b/src/components/validator/src/constraints/regex.cr @@ -4,6 +4,19 @@ # NOTE: As with most other constraints, `nil` and empty strings are considered valid values, in order to allow the value to be optional. # If the value is required, consider combining this constraint with `AVD::Constraints::NotBlank`. # +# ``` +# class User +# include AVD::Validatable +# +# def initialize(@username : String); end +# +# # this regex verifies that username contains alphanumeric chars +# # and some special characters (underscore, space and dash). +# @[Assert::Regex(/^[a-zA-Z0-9]+([_ -]?[a-zA-Z0-9])*$/)] +# property username : String +# end +# ``` +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/size.cr b/src/components/validator/src/constraints/size.cr index 4a70ec12..181c4436 100644 --- a/src/components/validator/src/constraints/size.cr +++ b/src/components/validator/src/constraints/size.cr @@ -1,5 +1,15 @@ # Validates that the `#size` of a `String` or `Indexable` value is between some minimum and maximum. # +# ``` +# class User +# include AVD::Validatable +# +# def initialize(@username : String); end +# +# @[Assert::Size(3..30)] +# property username : String +# end +# # # Configuration # # ## Required Arguments diff --git a/src/components/validator/src/constraints/unique.cr b/src/components/validator/src/constraints/unique.cr index 30ca580c..aabb7d8e 100644 --- a/src/components/validator/src/constraints/unique.cr +++ b/src/components/validator/src/constraints/unique.cr @@ -1,5 +1,15 @@ # Validates that all elements of an `Indexable` are unique. # +# ``` +# class School +# include AVD::Validatable +# +# def initialize(@rooms : Array(String)); end +# +# @[Assert::Unique] +# property rooms : Array(String) +# end +# # # Configuration # # ## Optional Arguments diff --git a/src/components/validator/src/constraints/url.cr b/src/components/validator/src/constraints/url.cr index 53ec37c2..bf5ebd2f 100644 --- a/src/components/validator/src/constraints/url.cr +++ b/src/components/validator/src/constraints/url.cr @@ -4,6 +4,16 @@ # NOTE: As with most other constraints, `nil` and empty strings are considered valid values, in order to allow the value to be optional. # If the value is required, consider combining this constraint with `AVD::Constraints::NotBlank`. # +# ``` +# class Profile +# include AVD::Validatable +# +# def initialize(@avatar_url : String); end +# +# @[Assert::URL] +# property avatar_url : String +# end +# # # Configuration # # ## Optional Arguments