Points lacking in Documentation

[rites...@anthropower.in]

There are couple of points that I see are lacking in the documentation which lead to confusion and/or consume a lot of time:

Link: https://docs.strongloop.com/display/public/LB/HasManyThrough+relations

Code:

Appointment.belongsTo(Physician, {as: 'foo', foreignKey: 'physicianId'});
Appointment.belongsTo(Patient, {as: 'bar', foreignKey: 'patientId'});

Q1: What is the as property?

It is not intuitive to know that value of as is the relation name configured in the JSON file. I spent quite a time to understand it. One can understand foreignKey property in code because it is also there in the JSON by the same name.

Q2: What is the keyThrough property?

Documentation explains it like this: 

"A hasManyThrough relation has a keyThrough property that indicates the foreign key property (field) name."

It doesn't indicate which foreignKey and why that foreignKey only? Mentioning (field) word doesn't see to add clarity.

Few more questions that came up while going through the documentation and trying to implement: 

1. Why keyThrough property is required? Aren't relations complete only by the use of foreign keys?
2. Why documentation made it more complicated by changing the foreignKey to fooId and barId and keyThrough property referencing them in an inverse way? How can one understand a real example (Patients and Physicians) containing arbitrary keys when example is trying to explain keyThrough?
   

Q3: Once relations are made, one will try to use them and there are three ways to add a related model

1. physician.patients.create
   
2. physician.patients.add
   
3. physician.patients.build

Which one to use in which scenario? Some real case would have helped.

Due to above points and similar ones which I find them lacking or not clearly explained, I often spend time making things work in the Loopback in a trial and error fashion.

I've few more points but would add them when time allows.