diff --git a/client/coral-embed-stream/src/graphql/index.js b/client/coral-embed-stream/src/graphql/index.js
index 3e5bcd259..1b4ac500b 100644
--- a/client/coral-embed-stream/src/graphql/index.js
+++ b/client/coral-embed-stream/src/graphql/index.js
@@ -2,7 +2,7 @@ import {gql} from 'react-apollo';
 import {add} from 'coral-framework/services/graphqlRegistry';
 import update from 'immutability-helper';
 import uuid from 'uuid/v4';
-import {insertComment, removeComment} from './utils';
+import {insertCommentIntoEmbedQuery, removeCommentFromEmbedQuery} from './utils';
 
 const extension = {
   fragments: {
@@ -165,7 +165,7 @@ const extension = {
           if (prev.asset.settings.moderation === 'PRE' || comment.status === 'PREMOD' || comment.status === 'REJECTED') {
             return prev;
           }
-          return insertComment(prev, parent_id, comment);
+          return insertCommentIntoEmbedQuery(prev, parent_id, comment);
         },
       }
     }),
@@ -175,7 +175,7 @@ const extension = {
           if (!['PREMOD', 'REJECTED'].includes(comment.status)) {
             return null;
           }
-          return removeComment(prev, comment.id);
+          return removeCommentFromEmbedQuery(prev, comment.id);
         },
       },
     }),
diff --git a/client/coral-embed-stream/src/graphql/utils.js b/client/coral-embed-stream/src/graphql/utils.js
index af5a355bc..3df4c2e51 100644
--- a/client/coral-embed-stream/src/graphql/utils.js
+++ b/client/coral-embed-stream/src/graphql/utils.js
@@ -27,7 +27,7 @@ function findAndInsertComment(parent, id, comment) {
   });
 }
 
-export function insertComment(root, id, comment) {
+export function insertCommentIntoEmbedQuery(root, id, comment) {
   if (root.comment) {
     if (root.comment.parent) {
       return update(root, {
@@ -75,24 +75,24 @@ function findAndRemoveComment(parent, id) {
   return update(parent, changes);
 }
 
-export function removeComment(root, id, comment) {
+export function removeCommentFromEmbedQuery(root, id) {
   if (root.comment) {
     if (root.comment.parent) {
       return update(root, {
         comment: {
           parent: {
-            $apply: (node) => findAndRemoveComment(node, id, comment),
+            $apply: (node) => findAndRemoveComment(node, id),
           },
         },
       });
     }
     return update(root, {
       comment: {
-        $apply: (node) => findAndRemoveComment(node, id, comment),
+        $apply: (node) => findAndRemoveComment(node, id),
       },
     });
   }
   return update(root, {
-    asset: {$apply: (asset) => findAndRemoveComment(asset, id, comment)},
+    asset: {$apply: (asset) => findAndRemoveComment(asset, id)},
   });
 }
diff --git a/graph/typeDefs.graphql b/graph/typeDefs.graphql
index 6d0520a50..7f5982779 100644
--- a/graph/typeDefs.graphql
+++ b/graph/typeDefs.graphql
@@ -253,10 +253,19 @@ type Comment {
   editing: EditInfo
 }
 
+# CommentConnection represents a paginable subset of a comment list.
 type CommentConnection {
+
+  # Indicates that there are more comments after this subset.
   hasNextPage: Boolean!
+
+  # Cursor of first comment in subset.
   startCursor: Date
+
+  # Cursor of last comment in subset.
   endCursor: Date
+
+  # Subset of comments.
   nodes: [Comment!]!
 }