diff --git a/docs/site/BelongsTo-relation.md b/docs/site/BelongsTo-relation.md
index da1bbe9f983e..48470ad6c6d4 100644
--- a/docs/site/BelongsTo-relation.md
+++ b/docs/site/BelongsTo-relation.md
@@ -76,17 +76,19 @@ export type OrderWithRelations = Order & OrderRelations;
 ```
 
 
-Definition of `belongsTo` relation can also include explicit `keyFrom`, `keyTo` and `name` attributes.
-
-- keyFrom is foreign key of the referenced model, whereas keyTo is primary key of referenced model, name is the referenced model name. Usage of keyFrom and keyTo in a belongsTo relation is similar to the use in legacy datasource juggler.
-- In the above example for the model Order, keyFrom is `customerId` and keyTo is `id`. keyFrom defaults to `{decorated-belongsTo-property-name}`, keyTo defaults to `id` and the referenced model name defaults to the decorated property name after stripping the trailing `Id` suffix.
-- In case in the above example, the property name `customerId` has to be customized to say `cust_id`, then the keyFrom,  keyTo and name values needs to be explicitly defined as `@belongsTo(() => Customer, { keyFrom: 'customerId', keyTo: 'id'}, { name: 'customer' })`.
-
-
 The definition of the `belongsTo` relation is inferred by using the `@belongsTo`
 decorator. The decorator takes in a function resolving the target model class
 constructor and designates the relation type. It also calls `property()` to
 ensure that the decorated property is correctly defined.
+Usage of belongsTo relation is similar to legacy datasource juggler.
+
+The `@belongsTo` decorator takes three parameters
+  - the target model Class,
+  - the relation definition has three attributes - keyFrom, keyTo, name
+    - keyFrom is a property name on the "source" model (e.g. Order.customerId). keyFrom attribute has become a dummy parameter and is not relevant any more with the recent changes to use the decorated target as the actual keyFrom value.
+    - keyTo is a property name on the "target" model, typically the primary key of the "target" model.
+    - name is the relation name model name.
+  - property definition, this creates a property decorator implicitly. The name attribute in the definition can be used to customize datasource column name.
 
 A usage of the decorator with a custom primary key of the target model for the
 above example is as follows:
@@ -94,7 +96,11 @@ above example is as follows:
 ```ts
 class Order extends Entity {
   // constructor, properties, etc.
-  @belongsTo(() => Customer, {keyTo: 'pk'})
+  @belongsTo(
+    () => Customer,
+    { keyFrom: 'customerId', keyTo: 'id', name: 'customer' },
+    { name: 'customer_id' }
+  )
   customerId: number;
 }
 
@@ -103,6 +109,25 @@ export interface OrderRelations {
 }
 ```
 
+
+The above example can also be trimmed as follows,
+- keyFrom defaults to `{decorated-property-name}`
+- keyTo is `id` and relation name defaults to `{decorated-property-name}` after stripping the trailing `Id` suffix.
+
+
+```ts
+class Order extends Entity {
+  // constructor, properties, etc.
+  @belongsTo(() => Customer, { keyTo: 'id' }),
+  customerId: number;
+}
+
+export interface OrderRelations {
+  customer?: CustomerWithRelations;
+}
+```
+
+
 ## Configuring a belongsTo relation
 
 The configuration and resolution of a `belongsTo` relation takes place at the