From b88993c4a36734435a6be1bfae0352cd2f1220c2 Mon Sep 17 00:00:00 2001
From: Sashko Stubailo <sashko@stubailo.com>
Date: Tue, 3 May 2016 17:41:12 -0700
Subject: [PATCH] Add `gql` to docs (#63)

---
 docs/source/apollo-client/core.md  | 48 +++++++++++++++++++++++++++---
 docs/source/apollo-client/react.md |  6 ++--
 2 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/docs/source/apollo-client/core.md b/docs/source/apollo-client/core.md
index 588d27b88c8..54dedb1039a 100644
--- a/docs/source/apollo-client/core.md
+++ b/docs/source/apollo-client/core.md
@@ -6,6 +6,46 @@ description: How to use the Apollo Client directly, without a view integration.
 
 Most of the time, when you use the Apollo Client, you'll do it through one of the view layer integrations. But sometimes, you just want to fetch some data directly and use it in your application logic, or your preferred view technology doesn't have an integration package.
 
+<h2 id="gql">gql template literals</h2>
+
+When using Apollo Client, you will often write your queries using multiline template literals. These literals need to be tagged with the `gql` tag, like this:
+
+```js
+const query = gql`
+  {
+    user(id: 5) {
+      username
+    }
+  }
+`
+```
+
+There are two ways to import and use the `gql` tag. You can either register it globally:
+
+```js
+// Register it globally
+import { registerGqlTag } from 'apollo-client/gql';
+registerGqlTag();
+
+// Now, in any part of your app you can use the gql tag
+const query = gql`...`;
+```
+
+Alternatively, you can import it in every file if you want to be more explicit:
+
+```js
+import gql from 'apollo-client/gql';
+
+const query = gql`...`;
+```
+
+This template literal tag serves two functions:
+
+1. It parses the query string.
+2. It tells developer tools like `eslint-plugin-graphql` which strings in your app are GraphQL queries, so that they can be treated specially.
+
+We hope to soon release a build tool you can run on your queries when deploying to production so that you can avoid the overhead of loading the GraphQL parser at runtime, much like Relay does with `Relay.QL`.
+
 <h2 id="queries">Queries</h2>
 
 The primary function of the Apollo Client is running GraphQL queries to retrieve data from the server. There are two ways to get data: running a query once and getting a single result, and running a query then watching the result via a callback.
@@ -97,7 +137,7 @@ import ApolloClient from 'apollo-client';
 const client = new ApolloClient();
 
 client.query({
-  query: `
+  query: gql`
     query getCategory($categoryId: Int!) {
       category(id: $categoryId) {
         name
@@ -154,7 +194,7 @@ The object returned from `QueryObservable#subscribe`. Includes four methods:
 - `refetch(variables: Object)` Refetch this query from the server. Think of it like a refresh button. This can take an object of new variables
 - `unsubscribe()` Notify the client to no longer care about this query. After this is called, none of the callbacks on the observer will be fired anymore. It's very important to call this when you are done with the query, because that is what lets the client know that it can clean up the data associated with this subscription. The view integrations will do this for you.
 - `stopPolling()` Stop an actively polling query.
-- `startPolling(pollInterval: number)` Start polling a query 
+- `startPolling(pollInterval: number)` Start polling a query
 
 #### Code sample
 
@@ -162,7 +202,7 @@ All of the concepts above seem a bit complicated, but it's not hard to use in pr
 
 ```js
 const queryObservable = client.watchQuery({
-  query: `
+  query: gql`
     query getCategory($categoryId: Int!) {
       category(id: $categoryId) {
         name
@@ -227,7 +267,7 @@ import ApolloClient from 'apollo-client';
 const client = new ApolloClient();
 
 client.mutate({
-  mutation: `
+  mutation: gql`
     mutation postReply(
       $token: String!
       $topic_id: ID!
diff --git a/docs/source/apollo-client/react.md b/docs/source/apollo-client/react.md
index 6c9e4f2ad07..2d325b1d546 100644
--- a/docs/source/apollo-client/react.md
+++ b/docs/source/apollo-client/react.md
@@ -14,7 +14,7 @@ npm install react-apollo --save
 
 <h2 id="apollo-provider">ApolloProvider</h2>
 
-Injects an ApolloClient instance into a React view tree. 
+Injects an ApolloClient instance into a React view tree.
 
 Basic Apollo version:
 
@@ -83,7 +83,7 @@ import Category from '../components/Category';
 function mapQueriesToProps({ ownProps, state }) {
   return {
     category: {
-      query: `
+      query: gql`
         query getCategory($categoryId: Int!) {
           category(id: $categoryId) {
             name
@@ -103,7 +103,7 @@ function mapQueriesToProps({ ownProps, state }) {
 function mapMutationsToProps({ ownProps, state }) {
   return {
     postReply: (raw) => ({
-      mutation: `
+      mutation: gql`
         mutation postReply(
           $topic_id: ID!
           $category_id: ID!