Merge f2f111b into c153385

docs/site/BelongsTo-relation.md

@@ -6,6 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/BelongsTo-relation.html
 ---
 
+{% include note.html content="There are some limitations to `Inclusion Resolver`. See [Limitations](Relations.md#limitations)." %}
+
 ## Overview
 
 {% include note.html content="
@@ -517,5 +519,3 @@ custom scope once you have the inclusion resolver of each relation set up.
 Check[HasMany - Query multiple relations](HasMany-relation.md#query-multiple-relations)
 for the usage and examples.
 
-{% include important.html content="There are some limitations of inclusion:. <br/>We don’t support recursive inclusion of related models. Related GH issue: [Recursive inclusion of related models](https://github.com/strongloop/loopback-next/issues/3454). <br/>It doesn’t split numbers of queries. Related GH issue: [Support inq splitting](https://github.com/strongloop/loopback-next/issues/3444). <br/>It might not work well with ObjectId of MongoDB. Related GH issue: [Spike: robust handling of ObjectID type for MongoDB](https://github.com/strongloop/loopback-next/issues/3456).
-" %}

docs/site/HasMany-relation.md

@@ -15,6 +15,8 @@ Using this relation with NoSQL databases will result in unexpected behavior,
 such as the ability to create a relation with a model that does not exist. We are [working on a solution](https://github.com/strongloop/loopback-next/issues/2341) to better handle this. It is fine to use this relation with NoSQL databases for purposes such as navigating related models, where the referential integrity is not critical.
 " %}
 
+{% include note.html content="There are some limitations to `Inclusion Resolver`. See [Limitations](Relations.md#limitations)." %}
+
 A `hasMany` relation denotes a one-to-many connection of a model to another
 model through referential integrity. The referential integrity is enforced by a
 foreign key constraint on the target model which usually references a primary
@@ -718,6 +720,3 @@ The `Where` clause above filters the result of `orders`.
 
 {% include tip.html content="Make sure that you have all inclusion resolvers that you need REGISTERED, and
 all relation names should be UNIQUE."%}
-
-{% include important.html content="There are some limitations of inclusion:. <br/>We don’t support recursive inclusion of related models. Related GH issue: [Recursive inclusion of related models](https://github.com/strongloop/loopback-next/issues/3454). <br/>It doesn’t split numbers of queries. Related GH issue: [Support inq splitting](https://github.com/strongloop/loopback-next/issues/3444). <br/>It might not work well with ObjectId of MongoDB. Related GH issue: [Spike: robust handling of ObjectID type for MongoDB](https://github.com/strongloop/loopback-next/issues/3456).
-" %}

docs/site/Relations.md

@@ -6,6 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/Relations.html
 ---
 
+{% include note.html content="There are certain limitations to `Inclusion Resolver`. See [Limitations](Relations.md#limitations)." %}
+
 ## Overview
 
 Individual models are easy to understand and work with. But in reality, models
@@ -56,3 +58,39 @@ application.
 
 To generate a `HasMany` or `BelongsTo` relation through the CLI, see
 [Relation generator](Relation-generator.md).
+
+## Limitations
+
+### Modifying related models' navigational properties
+
+Navigational properties of related models cannot be created, updated, saved,
+deleted or replaced, via the parent model. See its
+[GitHub pull request](https://github.com/strongloop/loopback-next/pull/4148).
+
+### Creating a model alongside its related models
+
+Creating related models must be created separately after the parent model is
+created. See its
+[GitHub issue](https://github.com/strongloop/loopback-next/issues/4435).
+
+### Filtering by parent model
+
+[Where filters](https://loopback.io/doc/en/lb3/Where-filter.html) such as those
+used by model queries (`create()`, `find()`, `replaceById()`, etc.) cannot be
+used to filter a model by the value of its parent model. See its
+[GitHub issue](https://github.com/strongloop/loopback-next/issues/4299).
+
+### Recursive inclusion of related models
+
+We don’t support recursive inclusion of related models. Related GH issue:
+[Recursive inclusion of related models](https://github.com/strongloop/loopback-next/issues/3454).
+
+### Splitting numbers of queries
+
+It doesn’t split numbers of queries. Related GH issue:
+[Support inq splitting](https://github.com/strongloop/loopback-next/issues/3444).
+
+### Handling of MongoDB `ObjectID` type
+
+It might not work well with ObjectID of MongoDB. Related GH issue:
+[Spike: robust handling of ObjectID type for MongoDB](https://github.com/strongloop/loopback-next/issues/3456).

docs/site/hasOne-relation.md

@@ -6,6 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/hasOne-relation.html
 ---
 
+{% include note.html content="There are some limitations to `Inclusion Resolver`. See [Limitations](Relations.md#limitations)." %}
+
 ## Overview
 
 {% include note.html content="
@@ -529,6 +531,3 @@ It is possible to query several relations or nested include relations with
 custom scope once you have the inclusion resolver of each relation set up.
 Check[HasMany - Query multiple relations](HasMany-relation.md#query-multiple-relations)
 for the usage and examples.
-
-{% include important.html content="There are some limitations of inclusion:. <br/>We don’t support recursive inclusion of related models. Related GH issue: [Recursive inclusion of related models](https://github.com/strongloop/loopback-next/issues/3454). <br/>It doesn’t split numbers of queries. Related GH issue: [Support inq splitting](https://github.com/strongloop/loopback-next/issues/3444). <br/>It might not work well with ObjectId of MongoDB. Related GH issue: [Spike: robust handling of ObjectID type for MongoDB](https://github.com/strongloop/loopback-next/issues/3456).
-" %}