From a9d883f2820d04233245fc49252ee1d3e2825dba Mon Sep 17 00:00:00 2001
From: Nora <nora.abdelgadir@ibm.com>
Date: Fri, 4 Jan 2019 14:42:10 -0500
Subject: [PATCH] docs: add specific relation decorators

---
 docs/site/Decorators_repository.md | 138 ++++++++++++++++++++++++++---
 1 file changed, 125 insertions(+), 13 deletions(-)

diff --git a/docs/site/Decorators_repository.md b/docs/site/Decorators_repository.md
index 32238e174b7d..bd2268df2b2b 100644
--- a/docs/site/Decorators_repository.md
+++ b/docs/site/Decorators_repository.md
@@ -106,7 +106,7 @@ If the model or datasource is already bound to the app, you can create the
 repository by providing their names instead of the classes. For example:
 
 ```ts
-// with `datasource` and `Todo` already defined.
+// with `db` and `Todo` already defined.
 app.bind('datasources.db').to(db);
 app.bind('models.Todo').to(Todo);
 
@@ -119,9 +119,6 @@ export class TodoController {
 
 ### Relation Decorators
 
-_This feature has not yet been released in alpha form. Documentation will be
-added here as this feature progresses._
-
 The relation decorator defines the nature of a relationship between two models.
 
 #### Relation Decorator
@@ -133,19 +130,134 @@ Register a general relation.
 _This feature has not yet been released in alpha form. Documentation will be
 added here as this feature progresses._
 
-#### Specific Relation Decorator
+#### BelongsTo Decorator
 
 Syntax:
 
-- `@belongsTo`
-- `@hasOne`
-- `@hasMany`
+- `@belongsTo(targetResolver: EntityResolver<T>, definition?: Partial<BelongsToDefinition>)`
+  - Many-to-one connection between models.
+  - A `Todo` belongs to a `TodoList`.
+  - See [BelongsTo relation](BelongsTo-relation.md) for more details.
+
+{% include code-caption.html content="todo.model.ts" %}
+
+```ts
+import {belongsTo} from '@loopback/repository';
+import {TodoList} from './todo-list.model';
+
+export class Todo extends Entity {
+  // properties
+
+  @belongsTo(() => TodoList)
+  todoListId: number;
+
+  // etc
+}
+```
+
+#### HasOne Decorator
+
+- `@hasOne(targetResolver: EntityResolver<T>, definition?: Partial<HasOneDefinition>)`
+  - One-to-one connection between models.
+  - A `TodoList` has one `image`.
+  - See [HasOne relation](hasOne-relation.md) for more details.
+
+{% include code-caption.html content="todo-list.model.ts" %}
+
+```ts
+import {hasOne} from '@loopback/repository';
+import {TodoListImage} from './todo-list-image.model';
+
+export class TodoList extends Entity {
+  @property({
+    type: 'number',
+    id: true,
+  })
+  id?: number;
+
+  // other properties
+
+  @hasOne(() => TodoListImage)
+  image: TodoListImage;
+
+  // etc
+}
+```
+
+{% include code-caption.html content="todo-list-image.model.ts" %}
+
+```ts
+import {belongsTo} from '@loopback/repository';
+import {TodoList} from './todo-list.model';
+
+export class TodoListImage extends Entity {
+  @property({
+    type: 'number',
+    id: true,
+  })
+  id: number;
+
+  // other properties
+
+  @belongsTo(() => TodoList)
+  todoListId?: number;
+
+  // etc
+}
+```
+
+#### HasMany Decorator
+
+- `@hasMany(targetResolver: EntityResolver<T>, definition?: Partial<HasManyDefinition>)`
+  - One-to-many connection between models.
+  - A `TodoList` has many `Todo`s.
+  - See [HasMany relation](HasMany-relation.md) for more details.
+
+{% include code-caption.html content="todo-list.model.ts" %}
+
+```ts
+import {hasMany} from '@loopback/repository';
+import {Todo} from './todo.model';
+
+export class TodoList extends Entity {
+  @property({
+    type: 'number',
+    id: true,
+  })
+  id?: number;
+
+  // other properties
+
+  @hasMany(() => Todo)
+  todos: Todo[];
+
+  // etc
+}
+```
+
+{% include code-caption.html content="todo.model.ts" %}
+
+```ts
+import {belongsTo} from '@loopback/repository';
+import {TodoList} from './todo-list.model';
+
+export class Todo extends Entity {
+  // other properties
+
+  @belongsTo(() => TodoList)
+  todoListId?: number;
+
+  // etc
+}
+```
+
+#### Other Decorators
+
+The following decorators are not implemented yet. To see their progress, please
+go to the
+[Relations epic](https://github.com/strongloop/loopback-next/issues/1450).
+
 - `@embedsOne`
 - `@embedsMany`
 - `@referencesOne`
 - `@referencesMany`
-
-Register a specific relation.
-
-_This feature has not yet been released in alpha form. Documentation will be
-added here as this feature progresses._