docs: update belongsTo docs to include keyFrom and keyTo

Fixes #2639

docs/site/BelongsTo-relation.md

@@ -43,6 +43,30 @@ related routes, you need to perform the following steps:
 This section describes how to define a `belongsTo` relation at the model level
 using the `@belongsTo` decorator to define the constraining foreign key.
 
+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 the legacy
+[datasource juggler](https://github.com/strongloop/loopback-datasource-juggler).
+
+The `@belongsTo` decorator takes three parameters:
+
+- `target model class` (required)
+- `relation definition` (optional) - has three attributes, keyFrom, keyTo, name
+  - `keyFrom` is a property name of the
+    foreign key on the "source" model. It is always set to the decorated property name,
+    which is customerId on Order model in the example.
+  - `keyTo` is a property name on the "target" model, typically the primary key
+    of the "target" model. `keyTo` attribute defaults to the id property on the target model,
+    which is "id" on Customer in the example.
+  - `name` is the name of the relation as defined in the repository. The relation name
+  is used in the repository constructor to define a [BelongsToAccessor](#configuring-a-belongsto-relation)
+  and [inclusion resolver](#enabledisable-the-inclusion-resolvers) to create a getter and map it to the relation.
+- `property definition` (optional) - creates a property decorator implicitly.
+  The name attribute in the definition can be used to customize datasource
+  column name.
+
 {% include code-caption.html content="/src/models/order.model.ts" %}
 
 ```ts
@@ -75,18 +99,45 @@ export interface OrderRelations {
 export type OrderWithRelations = Order & OrderRelations;
 ```
 
-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.
+The standard naming convention for the foreign key property in the source model
+is `relation name` + `Id` (for example, Order.customerId).
+
+- If the foreign key property name in the source model has to be customized,
+  the relation name has to be specified in the `name` attribute of the relation definition.
+  In addition, if you have a corresponding `hasMany` or `hasOne` relation in the target model,
+  (for example, a Customer has many Orders) the `keyTo` attribute of that corresponding relation needs to be stated explicitly.
+  Check the relation Metadata in [hasMany](#https://github.com/strongloop/loopback-next/blob/master/docs/site/HasMany-relation.md) and [hasOne](#https://github.com/strongloop/loopback-next/blob/master/docs/site/hasOne-relation.md) for more details.
+- In the following example, the foreign key property name is customized as
+  `cust_Id` instead of `customerId`. so the relation definition in the second
+  argument is explicitly passed to the `belongsTo` decorator.
+
+```ts
+class Order extends Entity {
+  // constructor, properties, etc.
+  @belongsTo(() => Customer, {keyFrom: 'cust_Id', name: 'customer'})
+  cust_Id: number;
+}
+```
+
+In the following example, the db column name of the foreign key is customized by
+passing the property definition in the third argument to the `belongsTo`
+decorator.
+
+```ts
+class Order extends Entity {
+  // constructor, properties, etc.
+  @belongsTo(() => Customer, {keyFrom: 'customerId'}, {name: 'customer_id'})
+  customerId: number;
+}
+```
 
-A usage of the decorator with a custom primary key of the target model for the
-above example is as follows:
+The `keyTo` attribute in the relation definition has to be stated explicitly,
+when the property of the target model for the belongsTo relation is not the id property in the target model.
 
 ```ts
 class Order extends Entity {
   // constructor, properties, etc.
-  @belongsTo(() => Customer, {keyTo: 'pk'})
+  @belongsTo(() => Customer, { keyTo: 'customized_target_property' }),
   customerId: number;
 }