From eb0b67a5353dfa183573abf1ac677df84baab29d Mon Sep 17 00:00:00 2001
From: Alex Suraci <asuraci@pivotal.io>
Date: Mon, 26 Jan 2015 16:18:49 -0800
Subject: [PATCH] improve/add docs around events API

[#86811810]

Signed-off-by: Atul Kshirsagar <atul.kshirsagar@gmail.com>
---
 client.go       |  1 +
 doc/api_lrps.md |  5 +++
 doc/events.md   | 85 +++++++++++++++++++++++++++++++++++++++++++++++++
 event_source.go | 12 +++++++
 4 files changed, 103 insertions(+)
 create mode 100644 doc/events.md

diff --git a/client.go b/client.go
index ecc26b4..44846c0 100644
--- a/client.go
+++ b/client.go
@@ -24,6 +24,7 @@ var ErrSubscribedToClosedHub = errors.New("subscribed to closed hub")
 var ErrHubAlreadyClosed = errors.New("hub already closed")
 
 //go:generate counterfeiter -o fake_receptor/fake_client.go . Client
+
 type Client interface {
 	CreateTask(TaskCreateRequest) error
 	Tasks() ([]TaskResponse, error)
diff --git a/doc/api_lrps.md b/doc/api_lrps.md
index d13f8b5..9b5b47b 100644
--- a/doc/api_lrps.md
+++ b/doc/api_lrps.md
@@ -114,4 +114,9 @@ Diego supports killing the ActualLRPs for a given `process_guid` at a given `ind
 DELETE /v1/actual_lrps/:process_guid/index/:index
 ```
 
+## Receiving events when Actual or Desired LRPs change
+
+To get server side event stream for changes to DesiredLRPs and ActualLRPs, see [Events](events.md).
+
+
 [back](README.md)
diff --git a/doc/events.md b/doc/events.md
new file mode 100644
index 0000000..367ada0
--- /dev/null
+++ b/doc/events.md
@@ -0,0 +1,85 @@
+# Events
+
+```
+GET /v1/events
+```
+
+Following types of events are emitted when changes to desired LRP and actual LRP are done:
+
+## Desire LRP create event
+
+When a new desired LRP is created a `DesiredLRPCreatedEvent` is emitted. Below the desired lrp created event is described:
+
+```
+{
+  "desired_lrp": {...}
+}
+```
+
+The field value of `desired_lrp` will be a `DesiredLRPResponse`, which is described in the [LRP API](lrps.md).
+
+## Desired LRP change event
+
+When a desired LRP is changed a `DesiredLRPChangedEvent` is emitted. Below the desired lrp changed event is described:
+
+```
+{
+  "desired_lrp_before": {...},
+  "desired_lrp_after": {...},
+}
+```
+
+The field value of `desired_lrp_before` and `desired_lrp_after` will be a `DesiredLRPResponse`, which is described in the [LRP API](lrps.md).
+
+
+## Desired LRP remove event
+
+When a desired LRP is deleted a `DesiredLRPRemovedEvent` is emitted. Below the desired lrp deleted event is described:
+
+```
+{
+  "desired_lrp": {...}
+}
+```
+
+The field value of `desired_lrp` will be a `DesiredLRPResponse`, which is described in the [LRP API](lrps.md).
+
+
+## Actual LRP create event
+
+When a new actual LRP is created a `ActualLRPCreatedEvent` is emitted. Below the actual lrp created event is described:
+
+```
+{
+  "actual_lrp": {...}
+}
+```
+
+The field value of `actual_lrp` will be a `ActualLRPResponse`, which is described in the [LRP API](lrps.md).
+
+
+## Actual LRP change event
+
+When a actual LRP is changed a `ActualLRPChangedEvent` is emitted. Below the actual lrp changed event is described:
+
+```
+{
+  "actual_lrp_before": {...},
+  "actual_lrp_after": {...},
+}
+```
+
+The field value of `actual_lrp_before` and `actual_lrp_after` will be a `ActualLRPResponse`, which is described in the [LRP API](lrps.md).
+
+
+## Actual LRP remove event
+
+When a new actual LRP is deleted a `ActualLRPRemovedEvent` is emitted. Below the actual lrp deleted event is described:
+
+```
+{
+  "actual_lrp": {...}
+}
+```
+
+The field value of `actual_lrp` will be a `ActualLRPResponse`, which is described in the [LRP API](lrps.md).
diff --git a/event_source.go b/event_source.go
index 26b0abe..77c4e44 100644
--- a/event_source.go
+++ b/event_source.go
@@ -50,12 +50,24 @@ func (e closeError) Error() string {
 }
 
 //go:generate counterfeiter -o fake_receptor/fake_event_source.go . EventSource
+
+// EventSource provides sequential access to a stream of events.
 type EventSource interface {
+	// Next reads the next event from the source. If the connection is lost, it
+	// automatically reconnects.
+	//
+	// If the end of the stream is reached cleanly (which should actually never
+	// happen), io.EOF is returned. If called after or during Close,
+	// ErrSourceClosed is returned.
 	Next() (Event, error)
+
+	// Close releases the underlying response, interrupts any in-flight Next, and
+	// prevents further calls to Next.
 	Close() error
 }
 
 //go:generate counterfeiter -o fake_receptor/fake_raw_event_source.go . RawEventSource
+
 type RawEventSource interface {
 	Next() (sse.Event, error)
 	Close() error