Apply suggestions from code review

Co-authored-by: Maryam Ziyad <maryamziyadm@gmail.com>

examples/distinct-object-types/distinct_object_types.bal

@@ -1,6 +1,5 @@
 import ballerina/io;
 
-// DistinctPerson is a proper subtype of Person
 class Person {
     public string name;
 
@@ -9,6 +8,7 @@ class Person {
     }
 };
 
+// `DistinctPerson` is a proper subtype of `Person`.
 distinct class DistinctPerson {
     public string name;
 
@@ -17,17 +17,19 @@ distinct class DistinctPerson {
     }
 }
 
-// SomeWhatDistinctPerson is a subtype of DistinctPerson since inherit the same type ID via inclusion
+// The `SomeWhatDistinctPerson` type is a subtype of the `DistinctPerson` type
+// since it includes the `DistinctPerson` type's type IDs via inclusion.
 class SomeWhatDistinctPerson {
     *DistinctPerson;
+
     public string name;
 
     function init(string name) {
         self.name = name;
     }
 }
 
-// EvenMoreDistinctPerson is a proper subtype of DistinctPerson since it has a additional type ID
+// EvenMoreDistinctPerson is a proper subtype of DistinctPerson since it has an additional type ID
 distinct class EvenMoreDistinctPerson {
     *DistinctPerson;
     public string name;
@@ -38,16 +40,16 @@ distinct class EvenMoreDistinctPerson {
 }
 
 public function main() {
-    Person person = new ("person");
+    Person person = new ("John Smith");
     io:println(person is DistinctPerson);
-    DistinctPerson distinctPerson = new ("distinctPerson");
+    DistinctPerson distinctPerson = new ("Alice Johnson");
     io:println(distinctPerson is Person);
 
-    SomeWhatDistinctPerson someWhatDistinctPerson = new ("someWhatDistinctPerson");
+    SomeWhatDistinctPerson someWhatDistinctPerson = new ("Michael Brown");
     io:println(someWhatDistinctPerson is DistinctPerson);
     io:println(distinctPerson is SomeWhatDistinctPerson);
 
-    EvenMoreDistinctPerson evenMoreDistinctPerson = new ("evenMoreDistinctPerson");
+    EvenMoreDistinctPerson evenMoreDistinctPerson = new ("Sarah Wilson");
     io:println(evenMoreDistinctPerson is DistinctPerson);
     io:println(distinctPerson is EvenMoreDistinctPerson);
 }

examples/distinct-object-types/distinct_object_types.md

@@ -1,7 +1,8 @@
 # Distinct object types
-For more explicit control over object type relations you can use `distinct` object types. Each distinct object type declaration has a unique type ID. When you include a distinct object type within another object type declaration, the new type's type ID set will include the type ID of the included type. When checking if a given object type `OSub` is a subtype of a distinct object type `OSuper` there is the additional requirement that `OSub` must contain all the type IDs of `OSuper`.
 
-This way you can achieve the same behavior as a nominal type system within the Ballerina's structured type system, which is useful for things such as GraphQL API interfaces.
+For more explicit control over object type relations you can use `distinct` object types. Each distinct object type declaration has a unique type ID. When you include a distinct object type within another object type declaration, the new type's type ID set will include the type IDs of the included type. When checking if a given object type `OSub` is a subtype of a distinct object type `OSuper` there is the additional requirement that `OSub` must contain all the type IDs of `OSuper`.
+
+This way you can achieve the same behavior as a nominal type system within Ballerina's structured type system, which is useful to support features such as GraphQL API interfaces.
 
 ::: code distinct_object_types.bal :::
 
@@ -12,3 +13,4 @@ This way you can achieve the same behavior as a nominal type system within the B
 - [Error subtyping](/learn/by-example/error-subtyping/)
 - [Defining classes](/learn/by-example/defining-classes/)
 - [Flexibly typed](https://ballerina.io/why-ballerina/flexibly-typed/)
+- [GraphQL service - Interfaces](https://ballerina.io/learn/by-example/graphql-interfaces/)