Update module and package md files

ballerina/Module.md

@@ -3,3 +3,114 @@
 This module provides features to validate the values that have been assigned to Ballerina types.
 
 The Ballerina `constraint` module facilitates APIs to do validations on the Ballerina types further with the use of annotations.
+
+### Constraint annotations
+
+This library provides the following annotations to validate the values that have been assigned to Ballerina types.
+
+| Ballerina Type                    | Annotation           | Supported Constraints                                                                                                  |
+|-----------------------------------|----------------------|------------------------------------------------------------------------------------------------------------------------|
+| `int`                             | `@constraint:Int`    | `minValue`, `maxValue`, `minValueExclusive`, `maxValueExclusive`, `maxDigits`, `maxIntegerDigits`, `maxFractionDigits` |
+| `float`                           | `@constraint:Float`  | `minValue`, `maxValue`, `minValueExclusive`, `maxValueExclusive`, `maxDigits`, `maxIntegerDigits`, `maxFractionDigits` |
+| `int`|`float`|`decimal` | `@constraint:Number` | `minValue`, `maxValue`, `minValueExclusive`, `maxValueExclusive`, `maxDigits`, `maxIntegerDigits`, `maxFractionDigits` |
+| `string`                          | `@constraint:String` | `length`, `minLength`, `maxLength`, `pattern`                                                                          |
+| `any[]`                           | `@constraint:Array`  | `length`, `minLength`, `maxLength`                                                                                     |
+| `constraint:Date`                 | `@constraint:Date`   | `option` - `PAST` or `FUTURE` or `PAST_OR_PRESENT` or `FUTURE_OR_PRESENT`                                              |
+
+The following example demonstrates how to apply constraint annotations to Ballerina types.
+
+```ballerina
+@constraint:String { pattern: re `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$` }
+public type Email string;
+
+@constraint:Date { option: constraint:PAST }
+public type DOB time:Date;
+
+public type Person record {|
+    @constraint:String { minLength: 5, maxLength: 10 }
+    string name;
+    @constraint:Int { minValue: 18, maxValue: 60 }
+    int age;
+    Email email;
+    @constraint:Array { minLength: 1, maxLength: 5 }
+    string[] phoneNumbers;
+    DOB dob;
+|};
+```
+
+### Constraint validation
+
+The `validate` function in this library can be used to validate the values that have been assigned to Ballerina types with respect to the constraints defined using the annotations.
+
+The following example demonstrates how to validate the values assigned to a Ballerina type.
+
+```ballerina
+public function main() returns error? {
+    Person person = {
+        name: "John",
+        age: 25,
+        email: "[email protected]",
+        phoneNumbers: ["1234567890", "0987654321"],
+        dob: { year: 1996, month: 5, day: 15 }
+    };
+    
+    Person|error personValidated = constraint:validate(person);
+    if personValidated is error {
+        io:println("Validation failed: " + personValidated.message());
+    } else {
+        io:println("Validation successful");
+    }
+}
+```
+
+### Custom error messages on validation failures
+
+Optionally a custom error message can be provided for each constraint. The following example demonstrates how to provide custom error messages for constraints.
+
+```ballerina
+@constraint:String { 
+    pattern: {
+        value: re `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$`,
+        message: "Invalid email address"
+    }
+}
+public type Email string;
+
+@constraint:Date {
+    option: {
+        value: constraint:PAST,
+        message: "Date of birth should be in the past"
+    },
+    message: "Invalid date found"
+}
+public type DOB time:Date;
+
+public type Person record {|
+    @constraint:String { 
+        minLength: 5, 
+        maxLength: {
+            value: 10,
+            message: "Name should be less than 10 characters"
+        }
+    }
+    string name;
+    @constraint:Int {
+        minValue: {
+            value: 18,
+            message: "Age should be greater than 18"
+        },
+        maxValue: 60
+    }
+    int age;
+    Email email;
+    @constraint:Array { 
+        minLength: {
+            value: 1,
+            message: "At least one phone number should be provided"
+        },
+        maxLength: 5 
+    }
+    string[] phoneNumbers;
+    DOB dob;
+|};
+```

ballerina/Package.md

@@ -4,6 +4,117 @@ This package provides features to validate the values that have been assigned to
 
 The Ballerina `constraint` package facilitates APIs to do validations on the Ballerina types further with the use of annotations.
 
+### Constraint annotations
+
+This library provides the following annotations to validate the values that have been assigned to Ballerina types.
+
+| Ballerina Type                    | Annotation           | Supported Constraints                                                                                                  |
+|-----------------------------------|----------------------|------------------------------------------------------------------------------------------------------------------------|
+| `int`                             | `@constraint:Int`    | `minValue`, `maxValue`, `minValueExclusive`, `maxValueExclusive`, `maxDigits`, `maxIntegerDigits`, `maxFractionDigits` |
+| `float`                           | `@constraint:Float`  | `minValue`, `maxValue`, `minValueExclusive`, `maxValueExclusive`, `maxDigits`, `maxIntegerDigits`, `maxFractionDigits` |
+| `int`|`float`|`decimal` | `@constraint:Number` | `minValue`, `maxValue`, `minValueExclusive`, `maxValueExclusive`, `maxDigits`, `maxIntegerDigits`, `maxFractionDigits` |
+| `string`                          | `@constraint:String` | `length`, `minLength`, `maxLength`, `pattern`                                                                          |
+| `any[]`                           | `@constraint:Array`  | `length`, `minLength`, `maxLength`                                                                                     |
+| `constraint:Date`                 | `@constraint:Date`   | `option` - `PAST` or `FUTURE` or `PAST_OR_PRESENT` or `FUTURE_OR_PRESENT`                                              |
+
+The following example demonstrates how to apply constraint annotations to Ballerina types.
+
+```ballerina
+@constraint:String { pattern: re `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$` }
+public type Email string;
+
+@constraint:Date { option: constraint:PAST }
+public type DOB time:Date;
+
+public type Person record {|
+    @constraint:String { minLength: 5, maxLength: 10 }
+    string name;
+    @constraint:Int { minValue: 18, maxValue: 60 }
+    int age;
+    Email email;
+    @constraint:Array { minLength: 1, maxLength: 5 }
+    string[] phoneNumbers;
+    DOB dob;
+|};
+```
+
+### Constraint validation
+
+The `validate` function in this library can be used to validate the values that have been assigned to Ballerina types with respect to the constraints defined using the annotations.
+
+The following example demonstrates how to validate the values assigned to a Ballerina type.
+
+```ballerina
+public function main() returns error? {
+    Person person = {
+        name: "John",
+        age: 25,
+        email: "[email protected]",
+        phoneNumbers: ["1234567890", "0987654321"],
+        dob: { year: 1996, month: 5, day: 15 }
+    };
+    
+    Person|error personValidated = constraint:validate(person);
+    if personValidated is error {
+        io:println("Validation failed: " + personValidated.message());
+    } else {
+        io:println("Validation successful");
+    }
+}
+```
+
+### Custom error messages on validation failures
+
+Optionally a custom error message can be provided for each constraint. The following example demonstrates how to provide custom error messages for constraints.
+
+```ballerina
+@constraint:String { 
+    pattern: {
+        value: re `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$`,
+        message: "Invalid email address"
+    }
+}
+public type Email string;
+
+@constraint:Date {
+    option: {
+        value: constraint:PAST,
+        message: "Date of birth should be in the past"
+    },
+    message: "Invalid date found"
+}
+public type DOB time:Date;
+
+public type Person record {|
+    @constraint:String { 
+        minLength: 5, 
+        maxLength: {
+            value: 10,
+            message: "Name should be less than 10 characters"
+        }
+    }
+    string name;
+    @constraint:Int {
+        minValue: {
+            value: 18,
+            message: "Age should be greater than 18"
+        },
+        maxValue: 60
+    }
+    int age;
+    Email email;
+    @constraint:Array { 
+        minLength: {
+            value: 1,
+            message: "At least one phone number should be provided"
+        },
+        maxLength: 5 
+    }
+    string[] phoneNumbers;
+    DOB dob;
+|};
+```
+
 ## Report issues
 
 To report bugs, request new features, start new discussions, view project boards, etc., go to the [Ballerina standard library parent repository](https://github.com/ballerina-platform/ballerina-standard-library).