From 90921e7c325ecab51b41d33a0053fb0e07099ed4 Mon Sep 17 00:00:00 2001
From: Urigo <uri.goldshtein@gmail.com>
Date: Thu, 18 May 2017 10:57:21 +0300
Subject: [PATCH 1/2] feat(subscriptions): added code comments

---
 src/index.js                  |  2 +-
 src/subscription/index.js     |  2 +-
 src/subscription/subscribe.js | 15 +++++++++++++--
 3 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/src/index.js b/src/index.js
index a031932503..3b3e3ae834 100644
--- a/src/index.js
+++ b/src/index.js
@@ -243,7 +243,7 @@ export type {
   ExecutionResult,
 } from './execution';
 
-export { subscribe, createSubscriptionSourceEventStream } from './subscription';
+export { subscribe, createSourceEventStream } from './subscription';
 
 // Validate GraphQL queries.
 export {
diff --git a/src/subscription/index.js b/src/subscription/index.js
index a5c82511f3..11b0a7f26d 100644
--- a/src/subscription/index.js
+++ b/src/subscription/index.js
@@ -1 +1 @@
-export { subscribe, createSubscriptionSourceEventStream } from './subscribe';
+export { subscribe, createSourceEventStream } from './subscribe';
diff --git a/src/subscription/subscribe.js b/src/subscription/subscribe.js
index d44264bd21..39b0f15ae6 100644
--- a/src/subscription/subscribe.js
+++ b/src/subscription/subscribe.js
@@ -34,7 +34,16 @@ import type {
   OperationDefinitionNode,
 } from '../language/ast';
 
-export function createSubscriptionSourceEventStream(
+/**
+ * Implements the "CreateSourceEventStream" and resolves the subscription
+ * event stream source.
+ *
+ * Returns an AsyncIterable
+ *
+ * A Source Stream represents the sequence of events, each of which will
+ * trigger a GraphQL execution corresponding to that event.
+ */
+export function createSourceEventStream(
   schema: GraphQLSchema,
   document: DocumentNode,
   rootValue?: mixed,
@@ -78,7 +87,7 @@ export function subscribe(
   variableValues?: ?{[key: string]: mixed},
   operationName?: ?string,
 ): AsyncIterator<ExecutionResult> {
-  const subscription = createSubscriptionSourceEventStream(
+  const subscription = createSourceEventStream(
     schema,
     document,
     rootValue,
@@ -138,6 +147,8 @@ function resolveSubscription(
     addPath(undefined, responseName)
   );
 
+  // resolveFieldValueOrError mirros ResolveFieldEventStream
+  // from subscriptions spec
   const subscription = resolveFieldValueOrError(
     exeContext,
     fieldDef,

From 6485d7959c62c56d2a3e931caba772b3b9c6d32f Mon Sep 17 00:00:00 2001
From: Lee Byron <lee@leebyron.com>
Date: Thu, 18 May 2017 14:39:03 +0200
Subject: [PATCH 2/2] Fix up comments

---
 src/subscription/subscribe.js | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/subscription/subscribe.js b/src/subscription/subscribe.js
index 39b0f15ae6..3caa5b71ce 100644
--- a/src/subscription/subscribe.js
+++ b/src/subscription/subscribe.js
@@ -35,13 +35,13 @@ import type {
 } from '../language/ast';
 
 /**
- * Implements the "CreateSourceEventStream" and resolves the subscription
- * event stream source.
+ * Implements the "CreateSourceEventStream" algorithm described in the 
+ * GraphQL specification, resolving the subscription source event stream.
  *
  * Returns an AsyncIterable
  *
- * A Source Stream represents the sequence of events, each of which will
- * trigger a GraphQL execution corresponding to that event.
+ * A Source Stream represents the sequence of events, each of which is 
+ * expected to be used to trigger a GraphQL execution for that event.
  */
 export function createSourceEventStream(
   schema: GraphQLSchema,
@@ -72,7 +72,7 @@ export function createSourceEventStream(
 }
 
 /**
- * Implements the "Subscribing to request" section of the GraphQL specification.
+ * Implements the "Subscribe" algorithm described in the GraphQL specification.
  *
  * Returns an AsyncIterator
  *
@@ -147,8 +147,9 @@ function resolveSubscription(
     addPath(undefined, responseName)
   );
 
-  // resolveFieldValueOrError mirros ResolveFieldEventStream
-  // from subscriptions spec
+  // resolveFieldValueOrError implements the "ResolveFieldEventStream"
+  // algorithm from GraphQL specification. It differs from 
+  // "ResolveFieldValue" due to providing a different `resolveFn`.
   const subscription = resolveFieldValueOrError(
     exeContext,
     fieldDef,