More code comments

client/coral-framework/helpers/plugins.js

@@ -41,6 +41,8 @@ function getComponentFragments(components) {
     }, {});
 
   Object.keys(res).forEach(key => {
+
+    // Assemble arguments for `gql` to call it directly without using template literals.
     res[key].spreads = `...${res[key].spreads.join('\n...')}\n`;
     const literals = ['', ...res[key].definitions.map(() => '\n')];
     res[key].definitions = gql.apply(null, [literals, ...res[key].definitions]);

client/coral-framework/hocs/withMutation.js

@@ -5,6 +5,10 @@ import {getMutationOptions} from 'coral-framework/services/registry';
 import {store} from 'coral-framework/services/store';
 import {getDefinitionName} from '../utils';
 
+/**
+ * Exports a HOC with the same signature as `graphql`, that will
+ * apply mutation options registered in the registry.
+ */
 export default (definitions, config) => WrappedComponent => {
   config = {
     ...config,

client/coral-framework/hocs/withQuery.js

@@ -2,6 +2,10 @@ import {graphql} from 'react-apollo';
 import {getQueryOptions} from 'coral-framework/services/registry';
 import {getDefinitionName, separateDataAndRoot} from '../utils';
 
+/**
+ * Exports a HOC with the same signature as `graphql`, that will
+ * apply query options registered in the registry.
+ */
 export default (definitions, config) => WrappedComponent => {
   config = {
     ...config,

client/coral-framework/services/registry.js

@@ -37,6 +37,8 @@ export function registerFragment(key, document) {
  * Register mutation options.
  *
  * Example:
+ * // state is the current redux state, which is sometimes
+ * // necessary to fill the optimistic response.
  * registerMutationOptions('PostComment', ({variables, state}) => ({
  *   optimisticResponse: {
  *     CreateComment: {
@@ -89,6 +91,8 @@ export function registerQueryOptions(key, config) {
  *       }`,
  *   },
  *   mutations: {
+ *     // state is the current redux state, which is sometimes
+ *     // necessary to fill the optimistic response.
  *     PostComment: ({variables, state}) => ({
  *       optimisticResponse: {
  *         [...]
@@ -143,6 +147,7 @@ export function getFragmentDocument(key) {
   let documents = fragments[key] ? fragments[key].documents : [];
   let fields =  fragments[key] ? `...${fragments[key].names.join('\n...')}\n` : ' __typename';
 
+  // Assemble arguments for `gql` to call it directly without using template literals.
   const main = `
     fragment ${key} on ${fragments[key].type} {
       ${fields}