[ci skip] docs(associations). Clarify usage of foreignKey with as. See #https://…

…github.com/sequelize/sequelize/issues/5496

docs/docs/associations.md

@@ -441,6 +441,20 @@ User.belongsToMany(Project);
 
 
 This will add the functions `add/set/get Tasks` to user instances.
 This will add the functions `add/set/get Tasks` to user instances.
 
 
+Remember, that using `as` to change the name of the association will also change the name of the foreign key. When using `as`, it is safest to also specify the foreign key.
+
+```js
+Invoice.belongsTo(Subscription)
+Subscription.hasMany(Invoice)
+```
+
+Without `as`, this adds `subscriptionId` as expected. However, if you were to say `Invoice.belongsTo(Subscription, { as: 'TheSubscription' })`, you will have both `subscriptionId` and `theSubscriptionId`, because sequelize is not smart enough to figure that the calls are two sides of the same relation. 'foreignKey' fixes this problem;
+
+```js
+Invoice.belongsTo(Subscription, , { as: 'TheSubscription', foreignKey: 'subscription_id' })
+Subscription.hasMany(Invoice, { foreignKey: 'subscription_id' )
+```
+
 ## Associating objects
 ## Associating objects
 
 
 Because Sequelize is doing a lot of magic, you have to call `Sequelize.sync` after setting the associations! Doing so will allow you the following:
 Because Sequelize is doing a lot of magic, you have to call `Sequelize.sync` after setting the associations! Doing so will allow you the following: