Add suggestions from previous PR

Add suggestions from
ballerina-platform#5709

examples/check-expression/check_expression.bal

@@ -1,5 +1,6 @@
 import ballerina/io;
 
+// Convert `bytes` to a `string` value and then to an `int` value.
 function intFromBytes(byte[] bytes) returns int|error {
     string|error res = string:fromBytes(bytes);
     // Explicitly check if the result is an error and 

examples/error-reporting/error_reporting.bal

@@ -37,6 +37,8 @@ public function main() {
         {name: "Bob", age: -1},
         {name: "Charlie", age: 30}
     ];
+    // Note how the Person value after the value for which validation fails is
+    // not processed
     error? err = validatePeople(people);
     if err is error {
         printError(err);

examples/error-subtyping/error_subtyping.bal

@@ -12,15 +12,15 @@ type InvalidI32Detail record {|
 // Error with the `InvalidIntDetail` type as the detail type.
 type InvalidIntError error<InvalidIntDetail>;
 
-// `error` with `InvalidI32Detail` as the detail type. Thus it is a subtype of `InvalidIntError`.
+// Error with `InvalidI32Detail` as the detail type. Thus it is a subtype of `InvalidIntError`.
 type InvalidI32Error error<InvalidI32Detail>;
 
 // Distinct error with the `InvalidIntDetail` type as the detail type and a unique type ID.
 // Therefore, this is a proper subtype of `InvalidIntError`, but doesn't have a subtype relationship 
 // with `AnotherDistinctIntError` because they have different type IDs.
 type DistinctIntError distinct error<InvalidIntDetail>;
 
-// Another `error` with `InvalidIntDetail` as the detail type and different type ID to `DistinctIntError`
+// Another distinct error with `InvalidIntDetail` as the detail type and different type ID to `DistinctIntError`
 // This is also a proper subtype of `InvalidIntError`, but doesn't have a subtype relationship with `DistinctIntError`
 type AnotherDistinctIntError distinct error<InvalidIntDetail>;
 

examples/error-subtyping/error_subtyping.md

@@ -1,8 +1,8 @@
 # Error subtyping
 
-If we want to identify if a given `error` type (say `ESub`) is a subtype of another error type (say `ESuper`), first we need to check if `ESuper` is a distinct error type. If it is not then `ESub` is a subtype if and only if the detail type of `ESub` is a subtype of the detail type of `ESuper`.
+If we want to identify if a given `error` type (say `ESub`) is a subtype of another error type (say `ESuper`), first we need to check if `ESuper` is a distinct error type. If it is not, then `ESub` is a subtype if and only if the detail type of `ESub` is a subtype of the detail type of `ESuper`.
 
-If more explicit control over error type relations is desired you can use `distinct` error types. Each declaration of a distinct error type has a unique type ID. If `ESuper` is a distinct error type there is the additional requirement that type ID of `ESub` must belong to the type ID set of `ESuper` for it to be a subtype.
+If more explicit control over error type relations is desired you can use `distinct` error types. Each declaration of a distinct error type has a unique type ID. If `ESuper` is a distinct error type there is the additional requirement that the type ID of `ESub` must belong to the type ID set of `ESuper` for it to be a subtype. In other words with distinct error types subtyping relationships behave similarl to nominal typing.
 
 Note that you can create subtypes of distinct error types by intersecting them with other error types.
 

examples/error-type-intersection/error_type_intersection.bal

@@ -12,36 +12,28 @@ type InputError error<InputErrorDetail>;
 
 type NumericError error<NumericErrorDetail>;
 
-type DistinctInputError distinct error<InputErrorDetail>;
-
-type DistinctNumericError distinct error<NumericErrorDetail>;
-
 // `NumericInputError` has detail type, `record {| int value |}`.
 type NumericInputError InputError & NumericError;
 
-// `DistinctNumericInputError` has type ids of both `DistinctInputError` and `DistinctNumericError`.
-type DistinctNumericInputError DistinctInputError & DistinctNumericError;
+type DistinctInputError distinct error<InputErrorDetail>;
 
-function createNumericInputError(int value) returns NumericInputError {
-    return error("Numeric input error", value = value);
-}
+type DistinctNumericError distinct error<NumericErrorDetail>;
 
-function createDistinctNumericInputError(int value) returns DistinctNumericInputError {
-    return error("Distinct numeric input error", value = value);
-}
+// `DistinctNumericInputError` has type IDs of both `DistinctInputError` and `DistinctNumericError`.
+type DistinctNumericInputError DistinctInputError & DistinctNumericError;
 
 public function main() {
-    NumericInputError e1 = createNumericInputError(5);
-    // `e1` belong to `InputError` since its detail type is a subtype of `InputErrorDetail`.
+    NumericInputError e1 = error("Numeric input error", value = 5);
+    // `e1` belongs to `InputError` since its detail type is a subtype of `InputErrorDetail`.
     io:println(e1 is InputError);
 
-    // `e1` doesn't belong to `DistinctInputError` since it doesn't have the type id of `DistinctInputError`.
+    // `e1` doesn't belong to `DistinctInputError` since it doesn't have the type ID of `DistinctInputError`.
     io:println(e1 is DistinctInputError);
 
-    DistinctNumericInputError e2 = createDistinctNumericInputError(5);
-    // `e2` belong to `InputError` since it's detail type is a subtype of `InputErrorDetail`.
+    DistinctNumericInputError e2 = error("Distinct numeric input error", value = 5);
+    // `e2` belongs to `InputError` since its detail type is a subtype of `InputErrorDetail`.
     io:println(e2 is InputError);
 
-    // `e2` belong to `DistinctInputError` since it's type id set include the type id of `DistinctInputError`.
+    // `e2` belongs to `DistinctInputError` since its type ID set include the type id of `DistinctInputError`.
     io:println(e2 is DistinctInputError);
 }

examples/error-type-intersection/error_type_intersection.md

@@ -1,6 +1,6 @@
 # Type intersection for error types
 
-If you intersect two `error` types, the resulting type's detail type is the intersection of the detail types of both types. Furthermore, if any of the types being intersected is a distinct type, then the resultant type's type ID set includes all the type IDs of that type. Thus it is a subtype of both types and this is how you create subtypes of `distinct` error types.
+If you intersect two `error` types, the resulting type's detail type is the intersection of the detail types of both types. Furthermore, if any of the types being intersected is a distinct type, then the resultant type's type ID set includes all the type IDs of that type. Thus it is a subtype of both types. This way, you can create an error type that is a subtype of multiple distinct types and also use a more specific detail type.
 
 ::: code error_type_intersection.bal :::