diff --git a/docs/decorator-reference.md b/docs/decorator-reference.md
index 203fea92ac..9ab1decbfd 100644
--- a/docs/decorator-reference.md
+++ b/docs/decorator-reference.md
@@ -19,15 +19,15 @@
     * [`@JoinColumn`](#joincolumn)
     * [`@JoinTable`](#jointable)
     * [`@RelationId`](#relationid)
-* [Subscriber and listener decorators](./listeners-and-subscribers.md)
-    * [`@AfterLoad`](./listeners-and-subscribers.md#afterload)
-    * [`@BeforeInsert`](./listeners-and-subscribers.md#beforeinsert)
-    * [`@AfterInsert`](./listeners-and-subscribers.md#afterinsert)
-    * [`@BeforeUpdate`](./listeners-and-subscribers.md#beforeupdate)
-    * [`@AfterUpdate`](./listeners-and-subscribers.md#afterupdate)
-    * [`@BeforeRemove`](./listeners-and-subscribers.md#beforeremove)
-    * [`@AfterRemove`](./listeners-and-subscribers.md#afterremove)
-    * [`@EventSubscriber`](./listeners-and-subscribers.md#what-is-a-subscriber)
+* [Subscriber and listener decorators](#subscriber-and-listener-decorators)
+    * [`@AfterLoad`](#afterload)
+    * [`@BeforeInsert`](#beforeinsert)
+    * [`@AfterInsert`](#afterinsert)
+    * [`@BeforeUpdate`](#beforeupdate)
+    * [`@AfterUpdate`](#afterupdate)
+    * [`@BeforeRemove`](#beforeremove)
+    * [`@AfterRemove`](#afterremove)
+    * [`@EventSubscriber`](#eventsubscriber)
 * [Other decorators](#other-decorators)
     * [`@Index`](#index)
     * [`@Transaction`, `@TransactionManager` and `@TransactionRepository`](#transaction-transactionmanager-and-transactionrepository)
@@ -463,6 +463,189 @@ export class Post {
 Relation id is used only for representation.
 The underlying relation is not added/removed/changed when chaning the value.
 
+## Subscriber and listener decorators
+
+#### `@AfterLoad`
+
+You can define a method with any name in entity and mark it with `@AfterLoad`
+and TypeORM will call it each time the entity 
+is loaded using `QueryBuilder` or repository/manager find methods.
+Example:
+
+```typescript
+@Entity()
+export class Post {
+    
+    @AfterLoad()
+    updateCounters() {
+        if (this.likesCount === undefined)
+            this.likesCount = 0;
+    }
+}
+```
+
+Learn more about [listeners](listeners-and-subscribers.md).
+
+#### `@BeforeInsert`
+
+You can define a method with any name in entity and mark it with `@BeforeInsert`
+and TypeORM will call it before the entity is inserted using repository/manager `save`.
+Example:
+
+```typescript
+@Entity()
+export class Post {
+    
+    @BeforeInsert()
+    updateDates() {
+        this.createdDate = new Date();
+    }
+}
+```
+Learn more about [listeners](listeners-and-subscribers.md).
+
+#### `@AfterInsert`
+
+You can define a method with any name in entity and mark it with `@AfterInsert`
+and TypeORM will call it after the entity is inserted using repository/manager `save`.
+Example:
+
+```typescript
+@Entity()
+export class Post {
+    
+    @AfterInsert()
+    resetCounters() {
+        this.counters = 0;
+    }
+}
+```
+
+Learn more about [listeners](listeners-and-subscribers.md).
+
+#### `@BeforeUpdate`
+
+You can define a method with any name in the entity and mark it with `@BeforeUpdate`
+and TypeORM will call it before an existing entity is updated using repository/manager `save`.
+Example:
+
+```typescript
+@Entity()
+export class Post {
+    
+    @BeforeUpdate()
+    updateDates() {
+        this.updatedDate = new Date();
+    }
+}
+```
+
+Learn more about [listeners](listeners-and-subscribers.md).
+
+#### `@AfterUpdate`
+
+You can define a method with any name in the entity and mark it with `@AfterUpdate`
+and TypeORM will call it after an existing entity is updated using repository/manager `save`.
+Example:
+
+```typescript
+@Entity()
+export class Post {
+    
+    @AfterUpdate()
+    updateCounters() {
+        this.counter = 0;
+    }
+}
+```
+
+Learn more about [listeners](listeners-and-subscribers.md).
+
+#### `@BeforeRemove`
+
+You can define a method with any name in the entity and mark it with `@BeforeRemove`
+and TypeORM will call it before a entity is removed using repository/manager `remove`.
+Example:
+
+```typescript
+@Entity()
+export class Post {
+    
+    @BeforeRemove()
+    updateStatus() {
+        this.status = "removed";
+    }
+}
+```
+
+Learn more about [listeners](listeners-and-subscribers.md).
+
+#### `@AfterRemove`
+
+You can define a method with any name in the entity and mark it with `@AfterRemove`
+and TypeORM will call it after the entity is removed using repository/manager `remove`.
+Example:
+
+```typescript
+@Entity()
+export class Post {
+    
+    @AfterRemove()
+    updateStatus() {
+        this.status = "removed";
+    }
+}
+```
+
+Learn more about [listeners](listeners-and-subscribers.md).
+
+#### `@EventSubscriber`
+
+Marks a class as an event subscriber which can listen to specific entity events or any entity events.
+Events are firing using `QueryBuilder` and repository/manager methods.
+Example:
+
+```typescript
+@EventSubscriber()
+export class PostSubscriber implements EntitySubscriberInterface<Post> {
+
+    
+    /**
+     * Indicates that this subscriber only listen to Post events.
+     */
+    listenTo() {
+        return Post;
+    }
+    
+    /**
+     * Called before post insertion.
+     */
+    beforeInsert(event: InsertEvent<Post>) {
+        console.log(`BEFORE POST INSERTED: `, event.entity);
+    }
+
+}
+```
+
+You can implement any method from `EntitySubscriberInterface`.
+To listen to any entity you just omit `listenTo` method and use `any`:
+
+```typescript
+@EventSubscriber()
+export class PostSubscriber implements EntitySubscriberInterface {
+    
+    /**
+     * Called before entity insertion.
+     */
+    beforeInsert(event: InsertEvent<any>) {
+        console.log(`BEFORE ENTITY INSERTED: `, event.entity);
+    }
+
+}
+```
+
+Learn more about [subscribers](listeners-and-subscribers.md).
+
 ## Other decorators
 
 #### `@Index`
@@ -564,4 +747,4 @@ Learn more about [custom entity repositories](working-with-entity-manager.md).
 
 Note: some decorators (like `@ClosureEntity`, `@SingleEntityChild`, `@ClassEntityChild`, `@DiscriminatorColumn`, etc.) aren't 
 documented in this reference because they are treated as experimental at the moment. 
-Expect to see their documentation in the future.
+Expect to see their documentation in the future.
\ No newline at end of file